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

GitHub Issues & Projects – GraphQL and webhook support for project status updates and more!

Today’s changelog brings you GraphQL and webhook support for project status updates and project custom field changes directly in the webhook event!

⚙ Using GraphQL and webooks with project status updates

Following our release earlier this year for project status updates, you can now interact with project status updates using GraphQL and webhooks. This unlocks new ways to automate how you provide and gather project status update information.

GraphQL

There is a new ProjectV2StatusUpdate GraphQL object to interact with project status updates, so you can view, create, update, and delete status updates.

Below is an example query to create a new project status update.

mutation {
  createProjectV2StatusUpdate(
    input: {projectId: "0123456", body: "We wrapped up our bug bash following the beta rollout. We're back on track for our GA date in August! 🚀", startDate: "2024-06-03", targetDate: "2024-08-09", status: ON_TRACK}
  ) {
    statusUpdate {
      id
      startDate
      targetDate
      body
      bodyHTML
      status
    }
  }
}

Webhooks

Project status updates are included in the new projects_v2_status_update webhook event, so you can understand and be notified when a new project status update is provided.

You must be subscribed to this event from the organization settings page to receive this information.
organization settings for webhook event

Below is an example of a webhook event.

{
    "action": "edited",
    "projects_v2_status_update": {
        "id": 32633,
        "node_id": "PVTSU_lADOBH2n9s4Ajp6VzX95",
        "project_node_id": "PVT_kwDOBH2n9s4Ajp6V",
        "creator": {
          ...
        },
        "body": "We've kicked off this project and are feeling confident in our rollout plan. More updates and demos to come next week!",
        "start_date": "2024-06-24",
        "target_date": "2024-08-16",
        "status": "ON_TRACK",
        "created_at": "2024-06-24T20:27:48Z",
        "updated_at": "2024-06-24T20:30:47Z"
    },
    "changes": {
        "body": {
            "from": "We're still planning this out and are kicking off soon.",
            "to": "We've kicked off this project and are feeling confident in our rollout plan. More updates and demos to come next week!"
        },
        "status": {
            "from": "INACTIVE",
            "to": "ON_TRACK"
        },
        "start_date": {
            "from": null,
            "to": "2024-06-24"
        },
        "target_date": {
            "from": null,
            "to": "2024-08-16"
        }
    },
    "organization": {
        ...
    },
    "sender": {
        ...
    }
}

➕ Using webhooks for project custom field changes

Project custom field changes are now included directly in the project_v2_item webhook event when a project item’s fields are edited, removing the need to send an additional GraphQL query. This gives you the previous and current field values to understand how project fields change over time and how long they have a particular value, allowing you to understand how long an item was In progress before moving to Done status.

Below is an example of the webhook which includes the previous and current value for single select, text, number, iteration, and date project custom fields using the changes parameter.

"changes": {
    "field_value": {
        "field_node_id": "PVTSSF_lADOBH2n9s4Aje1Izgb1kEs",
        "field_type": "single_select",
        "field_name": "Status",
        "project_number": 18,
        "from": {
            "id": "f75ad846",
            "name": "Todo",
            "color": "GREEN",
            "description": "This item hasn't been started"
        },
        "to": {
            "id": "47fc9ee4",
            "name": "In Progress",
            "color": "YELLOW",
            "description": "This is actively being worked on"
        }
    }
},

✨ Bug fixes and improvements

  • Added the convertProjectV2DraftIssueItemToIssue GraphQL mutation to convert drafts to issues
  • Fixed an error message when resizing columns in the table layout
  • Fixed errors when migrating a classic project to the new Projects experience
  • Fixed a bug where updating an issue in the project side panel didn’t reflect in the project view
  • Fixed the rendering of special characters in a single-select field description from the table layout cell dropdown
  • Fixed a bug where a space could not be added in project chart titles

✍️ Tell us what you think!

Join the conversation in the community discussion to share your feedback.

See how to use GitHub for project planning with GitHub Issues, check out what’s on the roadmap, and learn more in the documentation.

See more

GitHub Apps can now use the client ID to fetch installation tokens

Developers of GitHub Apps can simplify their application by using the client ID for both OAuth flows and the installation token flow.

To date, GitHub Apps have had two different IDs to manage – the application ID and the client ID. The application ID was only used to mint a JWT, subsequently used to fetch an installation token. The client ID is used with the OAuth flow to sign in users and request installations. These two values equally identify the application and the question of which one to use where caused unnecessary developer friction. You can now use the client ID in the place of the application ID when minting JWTs.

The application ID is not being deprecated at this time, nor are their plans to remove it. However, compatibility with future features will rely on use of the client ID, so updating is recommended.

The specific change allowed here is that when minting the JWT that proves your app is in posession of an application’s private key, you can use the client ID for the iss claim. Note that application IDs are ints, while client IDs are strings, if using a typed language.

require 'openssl'
require 'jwt'  # https://rubygems.org/gems/jwt

# Private key contents
private_pem = File.read("YOUR_PATH_TO_PEM")
private_key = OpenSSL::PKey::RSA.new(private_pem)

# Generate the JWT
 payload = {
 # issued at time, 60 seconds in the past to allow for clock drift
  iat: Time.now.to_i - 60,
  # JWT expiration time (10 minute maximum)
  exp: Time.now.to_i + (10 * 60),
--- # GitHub App's App ID
--- iss: "12345"
+++ # GitHub App's Client ID
+++ iss: "Iv23f8doAlphaNumer1c"
}

jwt = JWT.encode(payload, private_key, "RS256")
puts jwt

Note that Octokit still expects the use of the App ID in its setup – the Octokit SDK will be updated in the future to support use of the client ID.

You can find the client ID for your application in its settings page:

A screenshot of an app's settings, showing both the client ID and the application ID

Client IDs and application IDs are not secrets, and are expected to be visible to the end user – you do not need to change how you handle your IDs when making this update.

For more information about minting JWTs to get an installation token, see ‘Generating a JWT for a GitHub App’.

See more

New limits on scoped token creation for GitHub Apps

As a proactive measure to protect Github.com availability, GitHub Apps that attempt to create high-complexity scoped installation tokens will receive failures if they would individually reference too many repositories. At the time of release, no GitHub App is above these limits – the limit is approximately 8 times higher than what any app is consuming. See below for details on how complexity is calculated.

Scoped tokens allow a GitHub App to create an installation token that has just a subset of the privileges that the app has within an organization – both a reduced set of repositories, as well as permissions.
In this way, an application with many permissions and access to many repositories can still safely request a token that’s good for just the access that’s currently required, a useful least-privilege feature.

When requesting a scoped token, applications can indicate both the permissions and repositories that are desired. Both parameters are optional, and if either is omitted the full corresponding access will be given to the token, either all granted permissions or all accessible repositories.

The first limit being added is when the repositories are included in the token request – now, no more than 500 individual repositories can be listed.

The second limit is if the repositories are not listed but permissions are, and the application is installed on some repositories in the organization – as in, it has not been explicitly granted access to all repositories in the organization.
In that case, the limit is based on the number of permissions being requested and the number of repositories the application has access to. If the complexity limit is exceeded, the application will recieve an error: Too many repositories for installation, and provides the maximum number of repositories the application can have access to in order to succeed, as well as other options to reduce the complexity of your token, which are provided here as well.

To reduce the complexity of your token request, you can do one of the following:
1. Reduce the number of repositories that the application has access to in the organization.
2. Reduce the number of permissions requested for the token.
3. Set the application to have access to “all” of the organization’s repositories.
4. Not request a scoped token at all, and instead request a standard installation token.

Any of these options will reduce the complexity of the token and allow the application to fetch tokens for that organization once again.

To learn more about GitHub App scoped token issuance and installation, see our documentation:

  • “Generating an installation access token for a GitHub App”
  • “Reviewing and modifying installed GitHub Apps”
  • REST API: “Create an installation access token for an app”
    • See more

    Upcoming changes to repository insights

    Beginning January 8th, 2024, we will be making changes to the repository insights UI and API on GitHub for repositories with over 10,000 commits. The targeted UI and API have very low usage and rely on a legacy service we’re moving away from.

    User Interface Updates

    We are removing the following data:

    1. Under Insights > Contributors, we are removing addition/deletion counts for repositories with over 10,000 commits, as well as the dropdown that shows the graphs associated with additions and deletions. All the commit counts and commit count graphs will remain unchanged.
    Current page Repos with over 10,000 commits after the change is made
    The current Insights > Contributors tab The new tab which shows no dropdown for additions and deletions, and no addition and deletion counts
    1. Under Insights > Code Frequency, we will only show data for repos with under 10k commits.
    Current page Repos with over 10,000 commits after the change is made
    The current Insights > Code Frequency tab which shows a graph of additions and deletions over time The new tab which shows that there are too many commits to generate this graph

    REST API Modifications

    Alongside the UI changes, the following API changes will be implemented:

    1. The REST API responses for repositories with 10,000+ commits will report 0 values for the addition and deletion counts to improve performance. This impacts the /repos/{owner}/{repo}/stats/contributors endpoint to get all contributor commit activity
    2. The /repos/{owner}/{repo}/stats/code_frequency API endpoint will return a 422 status code for repos with 10,000 or more commits.
      • This is different from the previous two because this endpoint only returns additions/deletions, which we will no longer return for repos with over 10k commits. The previous two endpoints also return the total number of commits, which we will continue to generate.

    For users who continue to need detailed addition and deletion statistics for large-scale repositories, we suggest using the following Git command, as described in the Git documentation:

    git log --pretty="format:%m%ad----%ae%n%-(trailers:only,unfold)" --date=raw --shortstat --no-renames --no-merges

    See more

    GitHub Actions – Enforcing workflow scope when creating a release

    Starting today, apps and tokens used to create a release via the REST API endpoint will require the workflow scope or workflows:write permission in certain cases.

    The workflow scope or workflows:write will be required when creating a release that targets a commit SHA (target_commitish) that modifies an Actions workflow file and that SHA does not have an existing ref (branch head or tag).

    For more details see the REST API documentation or visit the GitHub Actions community if you have any questions.

    See more

    Additional repository metrics available via GraphQL API

    There are two new metrics available under the Repository object in the GraphQL API:

    • LastContributionDate – The most recent date there was any of the following activity: a commit to a repository’s default branch, opening an issue or discussion, answering a discussion, proposing a pull request, or submitting a pull request review. This is a good single-number metric to find projects that may be unmaintained or in need of archiving.
    • CommitCount – A monotonically increasing count of the total number of commits pushed to the default branch of the repository. Tracking the change in this over time will give a sense of the overall activity in the repository.

    These metrics are currently in public beta, so you will need to include a header to your GraphQL requests to opt-in:

    GraphQL-Features: ospo_metrics_api

    Additional documentation and context around these metrics is available in the github-ospo repo. Please provide your feedback on this discussion thread: https://github.com/orgs/community/discussions/72156

    See more

    Rate limits for /rate_limit REST API endpoint

    Up until recently, the /rate_limit REST API endpoint was not covered by the API's rate limit. While this allowed API consumers to fetch rate limit information whenever they wanted, it was also a potential vector for abuse.

    With that in mind, the /rate_limit endpoint is now covered by rate limits. Requests to the endpoint will not consume the primary rate limit quotas for the authenticated user. However, making a very high number of requests to the endpoint in a short period of time will trigger the secondary rate limits. Please follow the guidelines on avoiding the limits and what to do if you do hit them.

    These limits are not intended to cause friction for any normal usage of the API. Rather, their aim is to prevent abusive patterns. If you run into any problems with these limits for the /rate_limit endpoint, please contact GitHub Support.

    See more

    Deprecation: Source Imports REST API

    The Source Imports REST API allows integrators to programatically import internet-accessible Git repositories into GitHub.com – for example, from code hosting platforms like Bitbucket Cloud or GitLab.com.

    We're ending support for this API due to very low levels of usage and available alternatives. From 00:00 UTC on April 12, 2024, these endpoints will return an error. Integrators affected by this change will receive email alerts ahead of this deprecation.

    If you're using the Source Imports API, you'll need to update your integration by that date, or it will stop working. You can learn about alternatives to this API on the new "Programatically importing repositories" page on the GitHub Docs.

    See more

    GitHub Actions – Force cancel workflows

    Actions customers will now be able to clear stuck workflows by forcing a cancel request from the REST API. This is a new feature and the existing endpoint to cancel a workflow run will remain unchanged.

    Sometimes an Actions workflow can become stuck in a state that will not respond to a cancel request. This could block other workflows from executing and would often require customers to contact GitHub Support to resolve the issue. Going forward, customers can invoke force-cancel from the REST API, which will bypass conditions that would otherwise cause the workflow execution to continue. Customers should still only use force-cancel if the workflow fails to respond to POST /repos/{owner}/{repo}/actions/runs/{run_id}/cancel.

    For more details see the GitHub Actions workflow runs REST API documentation.

    For questions, visit the GitHub Actions community.

    To see what's next for Actions, visit our public roadmap.

    See more

    [Private Beta] Sign up for full access to the GHEC Enterprise Managed Users SCIM API

    Public documentation of the SCIM API for Enterprise Managed Users (EMU) is now available.

    Administrators of EMU enterprises can use a token with the admin:enterprise scope to make GET requests from SCIM clients. With this read access, you can directly reconcile GitHub's understanding of SCIM-defined users and groups with your federated identity groups for auditing purposes.

    Write requests to these APIs are possible through our published IdP applications, or through a new private beta that offers direct API access.

    To get write access to these APIs in beta, register your interest here.

    See more

    X-Accepted-GitHub-Permissions header for fine-grained permission actors

    A new header will be sent back to API callers that use the fine-grained permission model (GitHub Apps and fine-grained PATs) to help developers discover which permissions are needed to call an API route. This new header, x-accepted-github-permissions, contains the list of permissions required to access the endpoint.

    In the fine-grained permission model more than one permission may be needed to access an endpoint. Multiple sets of permissions may also be valid, since there are multiple ways to access data within GitHub. All valid sets are included in the header, each set separated by a semicolon (;).

    For example, when calling "List project collaborators", you'll recieve the header x-accepted-github-permissions: repository_projects=write; organization_projects=admin. This indicates that to get the list of collaborators on a project, you need either the repository_projects Write permission or the organization_projects Admin permission.

    This header is used in the same way as the x-accepted-oauth-scopes header for coarse-grained scope actors (OAuth apps and PATs (Classic)).

    To learn more about troubleshooting permissions issues with GitHub Apps and fine-grained PATs and to get more information about this header, see "Insufficient permission errors". To see the permissions needed for each endpoint, see "Permissions required for GitHub Apps" and "Permissions required for fine-grained PATs".

    See more

    Removal of source IP addresses from API error messages related to IP allow lists

    For security reasons, source IP addresses have been removed from error messages that are returned from the GitHub API when callers try to access protected resources from non-permitted IP addresses.

    To learn more about IP allow lists, visit Restricting network traffic to your enterprise with an IP allow list in the GitHub documentation.

    If you'd like to learn more about your source IP addresses, please contact GitHub Support.

    See more
    View more changes