A new identifier format for the GitHub GraphQL API

GitHub is changing the Global ID format used across its GraphQL API to accommodate future growth. The current format will not support the platform's projected scale over the coming years, according to the company. The new format is designed to provide more flexibility and scalability for handling requests.

As part of this change, all object identifiers in GraphQL will be updated, and some will become longer than before. Because the REST API also exposes an object's Global ID through its node_id field, the new format will affect REST responses as well. Identifiers will remain opaque strings and should not be decoded by clients.

Three-phase rollout

To give developers time to update implementations, caches, and stored data, GitHub is running a gradual, nine-month migration with an explicit deprecation schedule. The rollout proceeds in three phases, each lasting roughly three months.

  1. Introduce new format: The new Global IDs roll out type-by-type, starting with the least frequently requested object types and moving toward the most popular. Only newly created objects receive the new IDs during this phase; existing objects keep their current IDs. Since new IDs may be longer, GitHub advises ensuring you can store the extended values. No action is otherwise required during this phase.
  2. Migrate: Developers should update caches and data records. GitHub will provide migration tools that allow toggling between the old and new formats, with details to be published before launch. Both old and new IDs will work for referencing objects throughout this phase.
  3. Deprecate: All REST and GraphQL responses return the new IDs. Requests using old IDs will still function, but responses will contain only the new ID along with a deprecation warning. After this phase, GitHub will sunset the old format entirely, and requests made with old IDs will result in errors.

GitHub recommends that affected applications plan for the entire period and reach out through its support channels, indicating the app name so the team can assist should the change present any specific concerns.