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

Permissions filtering for organization fine-grained PATs

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

Dependabot alerts enterprise-level REST API

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

Dependabot alerts organizational-level REST API

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

Introducing fine-grained personal access tokens

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

New Dependabot alerts webhook

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

Organization-level APIs for Codespaces

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 role creation APIs are now available in public beta

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

Deprecation Notice: GraphQL for Packages

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

What’s new in Codespaces for Organizations

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

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

Increased file size limit when retrieving file contents via REST API

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

Enable OAuth Device Authentication Flow for Apps

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

Paused: Sunset of Deprecated Teams API Endpoints

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
View more changes