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

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