api

Subscribe to all “api” posts via RSS or follow GitHub Changelog on Twitter to stay updated on everything we ship.

~ cd github-changelog
~/github-changelog|main git log main
showing all changes successfully

Today, we’re introducing calendar-based versioning for the REST API to give API integrators a smooth migration path and plenty of time to update their integrations when we need to make occasional breaking changes to the API.

You can learn more in today’s blog post and on the new “API Versions” page in our docs.

If you’re using the REST API, you don’t need to take any action right now. We’ll get in touch with plenty of notice before we drop support for any old versions.

See more

Recently, GitHub added webhooks to our OpenAPI schema. Now, Webhook events and payloads in the GitHub documentation is built from the OpenAPI schema. The schema-generated documentation is more accurate and comprehensive and includes the payload structure for each event and action type.

Currently, the new webhook docs are available for the Free/Pro/Team and GitHub Enterprise Cloud plans. GitHub Enterprise Server and GitHub AE will get the new docs with the next version release.

Do you have ideas for improvement? Open a documentation issue to let us know.

See more

As part of the ongoing initiative to deprecate legacy global IDs, you will begin to see deprecation warnings for GraphQL node queries using the legacy ID format.

The deprecation warnings will look like this:

{
  "data": {
    "node": {
      "login": "ahoglund",
    }
  },
  "extensions": {
    "warnings": [
      {
        "type": "DEPRECATION",
        "message": "The id MDQ6VXNlcjM0MDczMDM= is deprecated. Update your cache to use the next_global_id from the data payload.",
        "data": {
          "next_global_id": "U_kgDOADP9xw"
        },
        "link": "https://docs.github.com"
      }
    ]
  }
}

This will not impact the data portion of the payload. We recommend using these deprecation warnings along with the X-Github-Next-Global-ID to begin migrating any of your caches that contain legacy IDs. More information on how to migrate can be found in our last update as well as in the GitHub documentation.

If you have any concerns about the rollout of this change impacting your usage of the GitHub GraphQL API, please contact us and include any relevant information, so that we can better assist you.

See more

We recently released organization-level API support that enables administrators to programmatically manage their organization-owned codespaces at scale. Today we're announcing that these APIs are generally available.

With organization APIs providing a wide range of management operations, organizations can seamlessly integrate GitHub Codespaces into their existing workflows to automate and manage their development processes at scale.

Organization-level APIs are generally available to GitHub Team and Enterprise Cloud plans. Here is a link to our documentation to get started:

See more

Organization administrators can now filter fine-grained personal access tokens (PATs) by their permissions in the organization settings UI. Both pending token requests and active tokens can be filtered by permission, such as issues_write and members_read.

image

After setting a filter, only tokens with that permission will be shown in the table.

To learn more about fine-grained PATs, see "Reviewing fine-grained personal access tokens" and "Managing requests for fine-grained personal access tokens".

See more

You can now retrieve all your Dependabot alerts at the GitHub enterprise level via the REST API. This new API endpoint supplements the recently introduced Dependabot alerts REST API, Dependabot alerts org-level REST API, and Dependabot alerts webhook.

For more information, see Dependabot alerts in the REST API reference or learn more about Dependabot alerts in our documentation.

See more

You can now retrieve all your Dependabot alerts at the GitHub organization level via the REST API. This new API endpoint supplements the recently introduced Dependabot alerts REST API and Dependabot alerts webhook.

This API is available on GitHub.com starting today and will also be available to GitHub Enterprise Server (GHES) users starting with version 3.8.

For more information, see Dependabot alerts in the REST API reference or learn more about Dependabot alerts in our documentation.

See more

Today we're enabling fine-grained personal access tokens (PATs) in Public Beta for all user accounts on GitHub.com. This new type of token gives developers and resource owners more control and visibility around token access. Learn more about this new token type in today's blog post.

These new tokens offer many more permissions to choose from, must be scoped to a specific organization or account, and must expire. Organization owners will also find new tools to manage tokens that can access their organization, and can require approval of those tokens before they may be used.

PATsv2-light2

You can try out the new token creation flow, and provide feedback in our community discussion.

For more information, see "Creating a fine-grained personal access token".

See more

API users can now integrate with a new dependabot_alert webhook, which matches the naming and structure of the recently introduced Dependabot alerts REST API. You should use this webhook in place of the existing repository_vulnerability_alert.

What's new

Improvements with the new webhook include:

  • More informative payload, including state and scope of the dependency, dismissal comments, and helpful information about a vulnerability (e.g. CVE ID, summary, description, CWEs, and reference URL).
  • Support for GitHub Apps with the Dependabot alerts read permission.
  • Actions on an alert now include the full set of created, dismissed, reopened, fixed, or reintroduced. See below for descriptions:
Action Action definition
created github has opened the Dependabot alert
dismissed GitHub user dismissed the alert with dismissed_reason and an optional dismissed_comment
reopened GitHub user manually reopened the previously-dismissed alert
fixed github detected the Dependabot alert is resolved
reintroduced github reopened the previously-fixed alert

Deprecation notice

The repository_vulnerability_alert webhook is being deprecated. In 2023, we plan to remove the existing repository_vulnerability_alert webhook, which is superseded by the dependabot_alert webhook. We will give integrators at least 3 months notice of this removal — keep an eye on the GitHub Changelog in 2023 for more information.

Learn more about the Dependabot alerts webhook in our documentation.

See more

We recently released a set of organization-level APIs (in beta) to enable administrators to programmatically manage their organization-owned codespaces at scale. Today we're releasing support for additional organization-level APIs based on the feedback that you shared with us. With this release, we've added support for the following REST API commands:

  • Manage organization-level codespaces secrets
    • List organization secrets
    • Get an organization public key
    • Get an organization secret
    • Create or update an organization secret
    • Delete an organization secret
    • List selected repositories for an organization secret
    • Set selected repositories for an organization secret
    • Add selected repository to an organization secret
    • Remove selected repository from an organization secret
  • Manage access control for organization-owned codespaces
    • Enable Codespaces for all members of the organization
    • Enable Codespaces for select members of the organization
    • Enable Codespaces for all members and outside collaborators of the organization
    • Disable Codespaces for the organization

Organization-level APIs are in beta for GitHub Team and Enterprise Cloud plans. Here are links to our documentation to get started:

If you have any feedback to help improve this experience, be sure to post it on our discussions forum.

See more

Custom repository roles enable Enterprise organization administrators to define and assign least-privilege roles for their repositories, beyond the standard Read, Triage, Write, Maintain, and Admin roles.

Now, REST API endpoints to create and update custom repository roles are available in a public beta for GitHub Enterprise Cloud customers. These new endpoints build on the existing custom repository role APIs that allow assignment of those roles to a team or user. The endpoints accept PATs from organization admins, as well as calls from properly authorized OAuth and GitHub apps.

These REST APIs will be supported in GitHub Enterprise Server 3.8, after they reach general availability in GitHub Enterprise Cloud.

Find out more about programmatically creating custom repository roles.

We'd love to get your feedback through your account team, or in our community Discussions board topic.

See more

GitHub Packages is being re-platformed, unlocking great capabilities such as fine-grained permissions, org-level publishing and increased performance.

Package registries on the new GitHub Packages architecture, including container registry and npm packages, no longer expose data through the GraphQL API. We recommend using the REST API instead.

In the coming months we will be migrating our other GitHub Package registries to this new architecture deprecating the GraphQL API for those registries as well.

If you have any questions, please contact GitHub Support.

See more

Today, we’re releasing capabilities that will enable developers and organizations to efficiently manage and confidently scale with Codespaces.

Retention setting for all individuals

To enable auto-cleanup of unused codespaces, inactive codespaces will now be automatically deleted if they have been unused after a period of 30 days. The retention period applies to all individual users on GitHub.com that are using Codespaces and can be adjusted to a maximum value of 30 days. With that, developers no longer need to remember to manually clean up old instances of dev environments that may be unintentionally generating additional costs. The retention counter for inactive codespaces can be reset by connecting to the instance. Additionally, developers will be notified via email and in-product messaging to help them stay informed about the auto-deletion.

Retention policy for organization administrators

Organization admins will also be able to set an organization-level retention constraint for their organization’s codespaces. The organization retention policy will override the individual default retention setting for organization-owned codespaces. With this, admins no longer need to remind individual teams to clean up stale codespaces thus minimizing wasteful resources and saving money for their organization.

We are also introducing support for organization level APIs and CLI commands in public beta so that admins can programmatically manage their organization-owned codespaces at scale. With this beta, organization admins can use the following REST API and CLI commands:

API

  • List all codespaces within your organization.
  • Get information on a specific codespace within your organization.
  • Stop, or delete codespaces within your organization.

CLI

  • List all codespaces within your organization.
  • Stop codespaces within your organization.
  • Delete codespaces within your organization.

Additionally, developers can also manage their own codespaces via APIs listed in our documentation that are generally available. With these APIs, you can perform CRUD (Create, Read, Update, and Delete) operations, view available machine types, and manage user-level and repository-level secrets for your codespaces seamlessly.

Get Started

The default 30 day retention setting will be applied to all new codespaces going forward across GitHub Free, Team and Enterprise Cloud plans. The max retention policy constraint is generally available and organization APIs are in beta for GitHub Team and Enterprise Cloud plans.
Here are links to our documentation to get started:

If you have any feedback to help improve this experience, be sure to post it on our discussions forum.

See more

Custom repository roles are now GA for GitHub.com and Enterprise Server 3.5.

Organization admins can create custom repository roles available to all repositories in their organization. Roles can be configured from a set of 35 fine grained permissions covering discussions, issues, pull requests, repos, and security alerts. Once a role is created, repository admins can assign a custom role to any individual or team in their repository.

Custom repository roles can be managed in the Repository roles tab of your Organization settings:

image

Custom repository roles are also supported in the GitHub REST APIs. The Custom Roles API can be used to list all custom repository roles in an organization, and the existing APIs for granting repository access to individuals and teams support custom repository roles.

To get started with custom repository roles, read the docs.

See more

Previously, the Get repository content REST API endpoint had a file size limit of 1 MB. That didn’t correspond to the Create or update file contents endpoint which has a file size limit of 100 MB. Now, both endpoints have a file size limit of 100 MB. However, requests for file contents larger than 1 MB must include the .raw custom media type in the Accept HTTP header, as shown here:

Accept: application/vnd.github.v3.raw

Read more about GitHub's REST API endpoints for repository contents.

See more

From today the OAuth Device Authorization flow feature must be manually enabled for all OAuth and GitHub Apps. This change reduces the likelihood of Apps being used in phishing attacks against GitHub users by ensuring integrators are aware of the risks and make a conscious choice to support this form of authentication.

If you own or manage an OAuth App or GitHub App that makes use of the OAuth Device Authorization flow, you can enable it for your App via its settings page:

Enable device flow

The OAuth Device Authorization flow API endpoints will respond with status code 400 to Apps that have not enabled this feature.

Learn more about the OAuth Device Authorization flow.

See more

We recently announced a plan to sunset deprecated Teams API endpoints over the coming weeks. On March 1, we conducted the first scheduled brownout for 12 hours.

As we gathered metrics and consumer feedback on the brownout, we formed a new understanding of its impact on our consumers and parallel work. Consequently, we are deciding to pause the remainder of the sunset. Instead, we will sunset deprecated Teams API endpoints over a new timeline in the coming months as we invest more deeply into API versioning and our Octokit SDKs.

If you are using a deprecated endpoint under a /teams/:team_id path, we continue to encourage you to switch to the /organizations/:org_id/team/:team_id path. Please refer to the REST API documentation to learn more about supported Teams API endpoints.

See more

On March 16 2022 the OAuth Device Authorization flow will become an "opt in" feature for all OAuth and GitHub Apps. This change reduces the likelihood of Apps being used in phishing attacks against GitHub users.

If you own or manage an OAuth App or GitHub App that makes use of the OAuth Device Authorization flow, you should enable it for your Apps via its settings page:

Enable device flow

The OAuth Device Authorization flow API endpoints will respond with status code 400 to Apps that have not opted in to this feature.

Learn more about the OAuth Device Authorization flow.

See more