GraphQL global ID migration update

Why the GraphQL ID format is changing

GitHub has finished the first phase of rolling out a new global ID format for its GraphQL API. All newly created objects now return IDs in this next format, which is a key step toward improving scalability and request speed. The previous ID format cannot accommodate projected growth, and the new format enables queries that are optimized for GitHub’s database clusters.

Legacy IDs will continue to work in the short term, but they will eventually be sunset. If your application stores references to GraphQL IDs—the value of the id field on any object—you should migrate those stored references to the next format. The migration tools described below let you update caches, data records, and other stored ID references before legacy support is removed.

Do you need to act?

Only applications that persist GraphQL ID values are affected. If you do not store these IDs, you can keep using the API without any changes. If your code decodes IDs, it may break because the underlying data format has changed; GitHub recommends treating IDs as opaque, unique strings that can be relied on directly as references.

Migrating to the next global ID format

To receive next-format IDs for older objects, add the X-Github-Next-Global-ID header to your GraphQL API requests. Set it to 1 to force every id field in the query response to use the next format. Set it to 0 to revert to the default behavior, which returns legacy or next IDs depending on when each object was created.

Here is an example request using curl:

$ curl \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "X-Github-Next-Global-ID: 1" \
  https://api.github.com/graphql \
  -d '{ "query": "{ node(id: \"MDQ6VXNlcjM0MDczMDM=\") { id } }" }'

The response will then contain the next ID:

{"data":{"node":{"id":"U_kgDOADP9xw"}}}

In this example, the legacy ID MDQ6VXNlcjM0MDczMDM= is used in the node query, and the response includes the ID in the next format. You can send requests with the legacy IDs you already have stored, capture the next-format IDs from the responses, and update your references accordingly. For bulk migrations, you can submit multiple node queries in a single API call using aliases.

An alternative approach uses the nodes field on a collection to convert many IDs at once. For example, to convert all repositories in an organization:

{
  organization(login: "github") {
    repositories(last: 10) {
      edges {
        cursor
        node {
          name
          id
        }
      }
    }
  }
}

If you have a reference to another unique field on the object—such as name—you can use this method to update references in bulk.

Note that setting X-Github-Next-Global-ID to 1 affects the return value of every id field in your query, not just those in node queries. Any requested id field will come back in the next format.

If you have concerns about how this change impacts your application, contact GitHub support and include your app name to help expedite assistance.