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

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

GitHub Codespaces allows teams and organizations to spin-up developer environments directly from a browser or through Visual Studio Code, without the hassle of setting up a brand new environment tailored to a specific repository.

We've been hard at work since our general availability announcement in August making Codespaces the best way for you to develop software, which is why we're so happy to announce several new features at GitHub Universe 2021.

We know that many developers use the gh CLI to speed up or fully automate daily tasks, and we've received dozens of requests to add Codespaces support to the CLI. As of today, the gh codespace (or gh cs for those saving keystrokes) command now allows developers to manage their codespaces from the GitHub CLI. In addition to codespace creation, listing, and starting/stopping, users can forward ports, set port visibility, SSH into their codespaces, and copy files to/from their codespaces.

# Create a new codespace via the CLI
gh codespace create --repo monalisa/octocat --branch main

We're especially excited about ssh access, as it allows developers who prefer to use editors like vim and emacs to more easily develop in Codespaces. Just gh cs ssh into your codespace and launch your editor of choice; we'll set up the environment and grab all your dotfiles so you're ready to develop in seconds.

# SSH into the codespace created above
gh codespace ssh -c monalisa-monalisa-octocat-1337h4x0r

Complimenting the CLI, we are also launching an API in beta. The API provides control plane operations around a user's codespaces including creating, starting/stopping, listing available machine types, and setting user secrets. These APIs will allow developers to build Codespaces integrations into their favorite editors and tools, as well as allow for additional automation around Codespaces.

# Stop a running codespace via the API
curl https://api.github.com/user/codespaces/monalisa-monalisa-octocat-1337h4x0r/stop \
  -H "Authorization: token <Personal Access Token>" \
  -X POST

We also know that security and privacy are critical, and we've gotten a lot of feedback on providing additional visibility options for forwarded ports beyond public and private. Today we're launching a third option: org visible ports, which are accessible to any user in the organization the codespace has been created in. This is great for securely collaborating with your teammates on new and exciting features in your codespaces.

# Make port 80 visible to all users in an org
gh codespace ports visibility 80:org -c monalisa-monalisa-octocat-1337h4x0r

Continuing with security improvements, we have also heard from developers having difficulty launching codespaces from devcontainers stored in private container registries. To make this easier, we are offering streamlined access to containers stored in the GitHub Container Registry; you no longer have to provide a Personal Access Token (PAT).

Speaking of devcontainers, we know that there's a wide gap between using a predefined devcontainer and building a custom devcontainer. To help make that transition a little easier, we're launching the ability to extend devcontainers with features, which include shells, package managers, programming languages, and other common tools. For example, adding Terraform to a supported base image is as easy as adding the following to your devcontainer.json.

"features": {
  "terraform": "latest"
}

If you have any feedback about these features, or Codespaces in general, we'd love to hear from you!

Learn more about all our newly released features:

See more

Organizations using GitHub Enterprise Cloud now have more granular control over the repository access permissions they can grant to users, with custom repository roles – now available in Beta.

A custom repository role is created by an organization owner, and is available across all repositories in that organization. Each role can be given a custom name, and a description. It can be configured from a set of over 40 fine grained permissions. Once created, repository admins can assign a custom role to any user, team or outside collaborator in their repository.

Custom repository roles can be created, viewed, edited and deleted via the new Repository roles tab in Organization settings.

Screenshot 2021-10-25 at 12 59 46 PM

Custom repository roles are also fully supported in the GitHub REST APIs. The Organizations 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 have been extended to support custom repository roles.

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

See more

We have graduated twenty-three of the twenty-five existing previews that were in our REST API.

Previously, REST API consumers needed to pass in a custom media-type via an HTTP accept header (example: Accept: application/vnd.github.ant-man-preview+json) with requests to get additional response fields or to be able to access specific endpoints.

The following are REST APIs that still require the accept header:

  • content_references (corsair preview) application/vnd.github.corsair-preview+json

  • code_of_conduct (scarlet-witch preview) application/vnd.github.scarlet-witch-preview+json

The header is no longer needed for the other twenty-three REST API previews that have been graduated.

For the remaining two previews the plan is to sunset the previews later this year. We are actively reaching out to any consumers of the REST APIs of those previews.

See more

You can now set whether a repository allows forking when creating or updating it using either the REST or GraphQL API.

Previously, APIs for creating and updating repositories didn't consider the fields allow_forking (REST) or forkingAllowed (GraphQL). Now, this field can be set before invoking the API to configure whether a repository allows forking.

For reference, see documentation for the REST API and GraphQL API.

See more

The Codes of Conduct API preview, which was accessible with the scarlet-witch-preview header, is being deprecated.

On December 6th, 2021, the fields behind this API preview will no longer be accessible. We recommend using the Get community profile metrics endpoint to retrieve information about a repository's code of conduct.

Email notifications will be sent to active users of the API preview throughout the deprecation period.

If you have any questions, please contact GitHub Support.

See more

GitHub will stop supporting API Authentication via Query Parameters with Actions on October 6th 2021 at 14:00 UTC. If you are passing credentials via query or path parameters, GitHub will respond with client errors. Please refer to this blog post for details on authenticating API requests to GitHub using the Authorization header.

Removal

  • October 6 2021 at 14:00 UTC
See more

The new GraphQL mutation createCommitOnBranch makes it easier to add, update, and delete files in a branch of a repository.

This new API offers a simpler way to commit changes compared to the existing Git database REST APIs. With the new createCommitOnBranch mutation, you do not need to manually create blobs and trees before creating the commit. This allows you to add, update, or delete multiple files in a single API call.

Commits authored using the new API are automatically GPG signed and are marked as verified in the GitHub UI. GitHub Apps can use the mutation to author commits directly or on behalf of users.


See the GraphQL API reference for more information on using createCommitOnBranch. You can also try it in the GraphQL API Explorer! If you need a refresher on how to use the GraphQL API, see our guide.

See more

As previously announced, on September 8th 2021 at 14:00 UTC, GitHub will stop supporting API Authentication via Query Parameters.

If you are passing credentials via query or path parameters, GitHub will respond with client errors. Please refer to this blog post for details on authenticating API requests to GitHub using the Authorization header.

Removal

  • September 8 2021 at 14:00 UTC

Please check the latest Enterprise release notes to learn in which version API Authentication via Query Parameters will be removed.

See more

As previously announced, on August 11 2021 at 14:00 UTC, GitHub will be removing the OAuth Application API to avoid unintentional logging of in-transit access tokens.

Please refer to this blog post on migrating to the replacement endpoints.

Removal

  • August 11 2021 at 14:00 UTC

Please check the latest Enterprise release notes to learn in which version the OAuth Application API will be removed.

See more