Translating GitHub resource IDs to global node IDs

github-global-node-id.md

GitHub associates a unique resource ID (or "database ID" or just "ID") with each API-accessible resource. For example, each issue, repository, and user has a global ID. In my limited experience with it, GitHub's REST API generally does not expose endpoints by which resources can be queried by ID (though it does have some undocumented endpoints). These resource IDs have been superseded by distinct global node IDs (node_id). GitHub's GraphQL API allows retrieval of a node by its ID, called a "direct node lookup".

As you can tell, you likely don't have much reason to interact with the older identifiers directly. I encountered this case when using the ZenHub API, which interfaces with repositories only by resource ID. In my case, I wanted to retrieve a list of recently-closed issues from a set of repositories identified only by their resource ID (and without their owner or name).

This would be possible using the undocumented repository information REST endpoint I mentioned above, but I wanted to use the GraphQL API due to the amount of repositories I was interested in. GitHub's GraphQL API does not expose a means of querying repositories (or any object, to my understanding) by these resource IDs, so we need to manually convert them.

It turns out that the global node IDs are base64 encodings of a human-readable format. Take, for example, DataBiosphere/azul:

query {
  azul: repository(owner:"DataBiosphere", name:"azul") {
    id
    databaseId
  }
}

{
  "data": {
    "azul": {
      "id": "MDEwOlJlcG9zaXRvcnkxMzkwOTU1Mzc=",
      "databaseId": 139095537
    }
  }
}

If we decode the global node ID, we can see the pattern:

$ echo "MDEwOlJlcG9zaXRvcnkxMzkwOTU1Mzc=" | base64 --decode
010:Repository139095537

which we can infer is roughly equivalent to {type_id}:{type_name}{resource_id}. I'm pretty new to GraphQL, so I may have butchered some of the terminology.

In any case, we can reverse this operation to calculate a global node ID from some resource identified only by resource ID:

$ echo -n "010:Repository139095537" | base64
MDEwOlJlcG9zaXRvcnkxMzkwOTU1Mzc=

query {
  node(id:"MDEwOlJlcG9zaXRvcnkxMzkwOTU1MzcK") {
    ... on Repository {
      nameWithOwner
    }
  }
}

{
  "data": {
    "node": {
      "nameWithOwner": "DataBiosphere/azul"
    }
  }
}

Interestingly, this will work even with the trailing newline (i.e., calling echo in the above example without the -n flag).

:D Happy to help, and it was a very fun reverse engineering challenge!

FYI I think the IDs are messagepack with prefixes for type.
Repo R_kgDOHXTDzg becomes [0, 494191566].
Commit C_kwDOHXTDztoAKDg5Y2Q2YzA1YTE2YmVmNWUwM2M0OWU5ODVlY2Y0ZWEyZjI1NDQ4MGQ becomes [0, 494191566, '89cd6c05a16bef5e03c49e985ecf4ea2f254480d'] (the string is the SHA of the commit).

I think that's why most ids start with a k: the array indicator in messagepack is a 144+(len) byte (144 is 0x90). 144 is 0b10010000 . Each base64 digit represents six bytes, so we're encoding 0b100100 = 36:

>>> encoding[0b100100]
'k'

Anything with a size <= 3 will start with a k, which seems to be what happens. Most (all?) actually start with kw which is a function of the array byte follewed by a literal zero (not sure why, but the first element is always a zero).

@travigd I think you nailed it! awesome work :)

Using msgpack is the key here, it seems - here is a python function that decodes a raw ID. You will need to pip install msgpack before running.

import base64
import msgpack

def decode_messagepack_id(encoded_id):
    # Remove the prefix and decode from base64
    base64_encoded = encoded_id.split('_')[1]
    # Adjust padding if necessary
    padding_needed = 4 - len(base64_encoded) % 4
    if padding_needed:
        base64_encoded += '=' * padding_needed
    messagepack_data = base64.b64decode(base64_encoded)
    # Decode using msgpack
    return msgpack.unpackb(messagepack_data)

# Adjusted example usage:
try:
    decoded_data = decode_messagepack_id("C_kwDOHXTDztoAKDg5Y2Q2YzA1YTE2YmVmNWUwM2M0OWU5ODVlY2Y0ZWEyZjI1NDQ4MGQ")
    print("Decoded Data:", decoded_data)
except Exception as e:
    print("Error decoding:", str(e))