Skip to content

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 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

Update on March 4, 2022: We have temporarily paused the sunset. Please read the official announcement for more information.


In early 2020, we moved the Teams API from a top-level path under /teams/:team_id to a scoped path under the organization that owns the team like /organizations/:org_id/team/:team_id and added support to make the API available under a named path like /orgs/:org/teams/:team_slug.

Over the next few weeks, we will be sunsetting the API endpoints under /teams/:team_id.

Timeline

Brownouts

  • March 1, 2022 for 12 hours starting at 14:00 UTC
  • March 8, 2022 for 24 hours starting at 14:00 UTC

If you make a request to an affected endpoint during the brownouts, GitHub will respond with a client error.

Removal

  • March 15, 2022 at 14:00 UTC

Affected endpoints

  • GET /teams/:team_id
  • PATCH /teams/:team_id
  • DELETE /teams/:team_id
  • GET /teams/:team_id/teams
  • GET /teams/:team_id/repos
  • GET /teams/:team_id/repos/:owner/:repo
  • PUT /teams/:team_id/repos/:owner/:repo
  • DELETE /teams/:team_id/repos/:owner/:repo
  • GET /teams/:team_id/projects
  • GET /teams/:team_id/projects/:project_id
  • PUT /teams/:team_id/projects/:project_id
  • DELETE /teams/:team_id/projects/:project_id
  • GET /teams/:team_id/members
  • GET /teams/:team_id/members/:username
  • PUT /teams/:team_id/members/:username
  • DELETE /teams/:team_id/members/:username
  • GET /teams/:team_id/memberships/:username
  • PUT /teams/:team_id/memberships/:username
  • DELETE /teams/:team_id/memberships/:username
  • GET /teams/:team_id/invitations

Steps to take

The easiest way to update your code is to switch to the /organizations/:org_id/team/:team_id path. If you're unsure of what org_id to use, you can GET the current team under /teams/:team_id and find the id field inside the organization hash in the response.

Please refer to the REST API documentation to learn more about supported Teams API endpoints.

See more

This release adds support for viewing fixed alerts to the GraphQL API. This update also adds the ability to access and filter by state, as well as access unique numeric identifier.

The additions include these new fields to a RepositoryVulnerabilityAlert:

  • number
  • fixed_at
  • fix_reason
  • state

And we're adding the ability to filter by state on the vulnerability alert object.

For more information, see Dependabot alerts in the GraphQL API reference.

See more

Users can now retrieve all their code scanning alerts at the GitHub organization level via the REST API. This new API endpoint supplements the existing repository level endpoint.

This API is available on GitHub.com starting today and will also be available to GitHub Enterprise Server users starting version 3.5.

Learn more about the code scanning REST API
Learn more about GitHub Advanced Security

See more

The GitHub metadata endpoint now contains our SSH host keys.
(We'll continue offering host key fingerprints as well.)

{
  // new entry
  "ssh_keys": [
    "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl",
    "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=",
    "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ=="
  ],
  // existing entry
  "ssh_key_fingerprints": [
    "SHA256_RSA": "nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8",
    "SHA256_ECDSA": "p2QAMXNIC1TJYWeIOttrVc98/R1BUFWu3/LiyKgUfQM",
    "SHA256_ED25519": "+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU"
  ],
  // ... rest of payload
}

These keys are in the OpenSSH known_hosts format for easy inclusion into existing known_hosts files.
This will make it easier to preconfigure systems which expect to connect via SSH.
For example, you can prime your CI runners with these keys before starting to fetch from GitHub.

The keys returned from the API include both SSH host keys that we're actively using, plus any that we're advertising via host key rotation for future use.
Currently, we're not offering any keys via rotation that aren't actively in use, but if we announce new host keys in the future, you can find them here as well during the rotation period.

See the meta API endpoint to learn more.

See more

GitHub upgraded its OpenAPI description to the OpenAPI Specification (OAS) 3.1.

Upgrading to OAS 3.1 will enable us to add GitHub Webhooks to the description, simplify the description of nullable schemas, and reduce the description size by removing duplicate nullable reference schemas.

The GitHub OpenAPI description contains more than 600 operations exposed in our API. For visual exploration of the API, you can load the description as a Postman Collection. Programmatically, the description can be used to generate mock servers, test suites, and bindings for languages not supported by Octokit.

The description is provided under two formats. The bundled version is preferred for most use cases as it makes use of OpenAPI components for reuse and readability. For tooling that doesn't support inline references to components, we also provide a fully dereferenced version.

We are currently still publishing the 3.0 version of the description, which is now generally available in the latest release. The 3.1 version of the description is being published in parallel and can be found in the descriptions-next folder in the github/rest-api-description repository. More information about GitHub's OpenAPI description can also be found in our documentation.

See more

We have released improvements to the code scanning API:

  • We've added the fixed_at timestamp to alerts. This is the first time that the alert was not detected in an analysis. You can use this data to better understand when code scanning alerts are being fixed.
  • We've enabled sorting of alert results using sort and direction on either created, updated or number. Use this to see the alerts that are most important to you first. For more information, see List code scanning alerts for a repository.
  • We've added a Last-Modified header to the alerts and alert endpoint response. For more information, see Last-Modified in the Mozilla documentation.
  • We've added relatedLocations to the SARIF response when you request a code scanning analysis. The field may contain locations which are not the primary location of the alert. See an example in the SARIF spec and read about getting a code scanning analysis for a repository.
  • We've added help and tags data to the webhook response alert rule object. For more information, see Code scanning alert webhooks events and payloads.
  • PATs with the public_repo scope now have write access for code scanning endpoints on public repos, if the user has permission. This is a bug fix and is now inline with the documentation.

For more information, see the Code scanning in the API reference.

See more