How to Use Commit Signing with GitHub Apps

[loujr]

How do you know that someone has not tampered with your code and pushed in a lot of commits claiming to be someone they're not? A verified commit is a signature on the changes you have made to your codebase. Commit signing provides a tamper seal that adds an extra level of assurance that the person who committed changes to a repository is the person they claim to be. This signature can be signed multiple different ways such as GPG, SSH, or S/MIME. If this signature is present, GitHub will mark this commit as verified.

Why would anyone need to sign a commit using a bot? Maybe your organization has a tightly controlled codebase that needs to be audited and commits need to be from verified sources. Maybe your CI/CD infrastructure has a lot of branch protection requirements and requires verified commits. Additionally, you might have a lot of contractors filter in and out of your organization. This functionality could also be a tool of last resort if your verified chain is broken or compromised in some way. This feature allows your development team to submit changes to your codebase and have a trusted third party integration verify authenticity of the origin of these commits.

Outlined in this article is a step by step process of uploading a file to a repository and having the commit signed by a GitHub App. In this example, we will be using app-evil-corp bot to sign commits on our test repository on behalf of Evil Corp our favorite fictional corporation from the show Mr. Robot.

In order to set up GitHub App commit signing. You first must create and install a GitHub App and obtain a GitHub App Installation Token. For more information on how to create a GitHub App, please check out Creating a GitHub App and Installing GitHub Apps for GitHub App installation instructions. To obtain a GitHub App Installation Token, please check out the community article GitHub App Installation Token and Authenticating as a GitHub App.

There are three steps to using GitHub App commit signing:

1. Create a Tree
2. Create a Commit
3. Update a Reference

Creating a Tree

A tree is an object that allows you to create a hierarchy between files in a git repository. Without a tree, there is no way to associate all the tracked blob files and their contents. Blob is just a fancy way of saying its a whole bunch of compressed data (using zlib) and stored in an object database. A tree is really an index of all that information that explains which corresponding file belong to which directory.

To create a tree, curl the following endpoint Create a tree. For GitHub App commit signing, the following parameters are needed:

base_tree - This is the SHA of the branch you have made your commit. In this example, this SHA is the last commit sha for the main branch of test repository repo-test555.

tree - build's a new tree object on this branch requires an array of objects

path - file that you are referencing in this tree

mode - permissions of the file referenced in your tree can be one of 100644 for file (blob), 100755 for executable (blob), 040000 for subdirectory (tree), 160000 for submodule (commit), or 120000 for a blob that specifies the path of a symlink.

type - blob, tree, or commit

content - the content you want the file to have. GitHub will write this blob out and use that SHA for this entry. Use either this, or tree.sha.

Note: To find the full SHA of your last commit, you can look at the commits history of your repository. To copy the SHA, click the square next to the commit that says: Copy the full SHA

In this example, the file helloworld.py was uploaded with the permissions 644 to repository Repo-Test555. The file is a blob file and contains the message hello world.

curl -H "Accept: application/vnd.github.v3+json" -H "Authorization: token ghs_T3ikErpqpHW6UB7Nh07P2GhtdnVjl81DstQR" -H "Accept: application/vnd.github.v3+json" https://api.github.com/repos/the-evil-corporation/repo-test555/git/trees -d'{"base_tree": "10f3a75fa75d008acb9f1cb00c0121d397643c44","tree":[{"path": "helloworld.py","mode": "100644","type": "blob","content": "hello world"}]}' 

{
  "sha": "b12fd1716b81a52f233940c82ab67f6500238701",
  "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/trees/b12fd1716b81a52f233940c82ab67f6500238701",
  "tree": [
    {
      "path": "CODEOWNERS",
      "mode": "100644",
      "type": "blob",
      "sha": "96d7d7dd14f6bdfd4dd72fbed5438728c13d4062",
      "size": 83,
      "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/blobs/96d7d7dd14f6bdfd4dd72fbed5438728c13d4062"
    },
    {
      "path": "docs",
      "mode": "040000",
      "type": "tree",
      "sha": "567403355b2d8f297ed90e9c21f7d73c33f97299",
      "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/trees/567403355b2d8f297ed90e9c21f7d73c33f97299"
    },
    {
      "path": "github-app-codesign",
      "mode": "040000",
      "type": "tree",
      "sha": "26fe51ed1b51d24ea5b0de7cb2a69b2fd1c9b361",
      "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/trees/26fe51ed1b51d24ea5b0de7cb2a69b2fd1c9b361"
    },
    {
      "path": "helloworld.py",
      "mode": "100644",
      "type": "blob",
      "sha": "95d09f2b10159347eece71399a7e2e907ea3df4f",
      "size": 11,
      "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/blobs/95d09f2b10159347eece71399a7e2e907ea3df4f"
    },
    {
      "path": "pull_request_template.md",
      "mode": "100644",
      "type": "blob",
      "sha": "8d451bf228cc9143b328f39eb0562a90f461987b",
      "size": 9429,
      "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/blobs/8d451bf228cc9143b328f39eb0562a90f461987b"
    },
    {
      "path": "python_hash.py",
      "mode": "100644",
      "type": "blob",
      "sha": "3172a3e2f8d2a763c00ffcfde081f20271c88f3c",
      "size": 667,
      "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/blobs/3172a3e2f8d2a763c00ffcfde081f20271c88f3c"
    },
    {
      "path": "python_merge.py",
      "mode": "100644",
      "type": "blob",
      "sha": "0c935ab1eea4affad86938fb010e46956886b5de",
      "size": 704,
      "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/blobs/0c935ab1eea4affad86938fb010e46956886b5de"
    },
    {
      "path": "python_sort.py",
      "mode": "100644",
      "type": "blob",
      "sha": "d5c93c9a0dc35815109773278192bcfa0668ca03",
      "size": 441,
      "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/blobs/d5c93c9a0dc35815109773278192bcfa0668ca03"
    },
    {
      "path": "python_two.py",
      "mode": "100644",
      "type": "blob",
      "sha": "70b7682aacfd9ee9db9497f8f40deceadebf7578",
      "size": 14,
      "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/blobs/70b7682aacfd9ee9db9497f8f40deceadebf7578"
    },
    {
      "path": "requirements.txt",
      "mode": "100644",
      "type": "blob",
      "sha": "e07a4bf432b70b71a7451394fcf499741ad2381e",
      "size": 574,
      "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/blobs/e07a4bf432b70b71a7451394fcf499741ad2381e"
    },
    {
      "path": "test-ipython-notebook.ipynb",
      "mode": "100644",
      "type": "blob",
      "sha": "7d6b30e423bd57905c4894eb22cd9a27aaaeb9c9",
      "size": 778,
      "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/blobs/7d6b30e423bd57905c4894eb22cd9a27aaaeb9c9"
    },
    {
      "path": "test-restructured-text.rst",
      "mode": "100644",
      "type": "blob",
      "sha": "6ef6867ba765d7c00c9c893c0d6617b024415ba4",
      "size": 575,
      "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/blobs/6ef6867ba765d7c00c9c893c0d6617b024415ba4"
    }
  ],
  "truncated": false
}

The following response was received after making this API call. A tree object was created containing the contents of repo-test555.

Note: The SHA response b12fd1716b81a52f233940c82ab67f6500238701 is critical for making a commit. Please retain this value in your response.

Create a Commit

After a new tree is created, a new commit must also be made. This commit contains both the commit message as well as the SHA of the new tree and the SHA of the base branch. To create a Commit, curl the following endpoint Create a Commit. Using a GitHub App Installation Token will skip the need to specify a PGP Key, instead GitHub will sign the commit using their PGP Key through the GitHub App. To use GitHub App commit signing, you will need the following parameters:

message - The commit message of verified commit

parents - The commit SHA of the branch you made your commits

tree - The SHA that was returned after you created your new tree

curl -H "Accept: application/vnd.github.v3+json" -H "Authorization: token ghs_T3ikErpqpHW6UB7Nh07P2GhtdnVjl81DstQR" https://api.github.com/repos/the-evil-corporation/repo-test555/git/commits -d '{"message": "Test GitHub Commit Message", "parents": ["10f3a75fa75d008acb9f1cb00c0121d397643c44"], "tree":"b12fd1716b81a52f233940c82ab67f6500238701"}'

{
  "sha": "378b0bf1366719b46e9f9a2c99ef85676a8f985e",
  "node_id": "C_kwDOH3Q4EtoAKDM3OGIwYmYxMzY2NzE5YjQ2ZTlmOWEyYzk5ZWY4NTY3NmE4Zjk4NWU",
  "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/commits/378b0bf1366719b46e9f9a2c99ef85676a8f985e",
  "html_url": "https://github.com/the-evil-corporation/repo-test555/commit/378b0bf1366719b46e9f9a2c99ef85676a8f985e",
  "author": {
    "name": "app-evil-corp[bot]",
    "email": "113119115+app-evil-corp[bot]@users.noreply.github.com",
    "date": "2023-03-06T19:01:13Z"
  },
  "committer": {
    "name": "GitHub",
    "email": "[email protected]",
    "date": "2023-03-06T19:01:13Z"
  },
  "tree": {
    "sha": "96998a98fc5a5d6763ce9cad6225cfe7d9dc1c06",
    "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/trees/96998a98fc5a5d6763ce9cad6225cfe7d9dc1c06"
  },
  "message": "Test GitHub Commit Message",
  "parents": [
    {
      "sha": "0e6295d953f6baeb050fc7bcb2a58715fcc6ca6e",
      "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/commits/0e6295d953f6baeb050fc7bcb2a58715fcc6ca6e",
      "html_url": "https://github.com/the-evil-corporation/repo-test555/commit/0e6295d953f6baeb050fc7bcb2a58715fcc6ca6e"
    }
  ],
  "verification": {
    "verified": true,
    "reason": "valid",
    "signature": "-----BEGIN PGP SIGNATURE-----\n\nwsBcBAABCAAQBQJkBjh6CRBK7hj4Ov3rIwAAxjMIAGXz+wO2fTh7C5cKoeWKBMBM\nqy5SiMIt5BD//dP6WJgJCwcg5fFZxlVg6nHST+CoU5oQmQITa50zR61wEfDSrsvu\ntBHILQsa7X22oPf6lZ0LC0HdcY03re0F3PT54o8cnIYZHVFhgQnuJpvqTcsvgFAO\nKXvGH+T0MpSLGo38Mf3DWzCEvojK3eLPLFAQMeAAAJR8r39elry9DXUrvpvI0kvb\nqI/WuW0VVU86itt13iyToDeJHNhzGda9bIrd7tfpDroUPqtevMT0sy7hcwzuSzNf\nma8Y0lBciMpzDT38+ISZhM/bnuG/+HOXcpH2OBa+f5XDStZVqdv0o49oYLNHf6Q=\n=pi0v\n-----END PGP SIGNATURE-----\n",
    "payload": "tree 96998a98fc5a5d6763ce9cad6225cfe7d9dc1c06\nparent 0e6295d953f6baeb050fc7bcb2a58715fcc6ca6e\nauthor app-evil-corp[bot] <113119115+app-evil-corp[bot]@users.noreply.github.com> 1678129273 +0000\ncommitter GitHub <[email protected]> 1678129273 +0000\n\nTest GitHub Commit Message"
  }
}

On the response, you can see the verification object. This object contains the verified key which is a boolean value. If the value is true, the commit was verified. If the value is false, the commit was not verified. Further, the PGP signature is included in the signature key. Because you have used the GitHub App Installation token, GitHub is able prove that you have access to this GitHub App and uses their (GitHub's) PGP key to sign the commit.

Note A the time of making this commit, the commit is not referenced in the main branch. It exists as a commit on a fork outside of the repository until we update the reference. This is apparent when you view the html_url of the commit.

Update a Reference

Updating a reference is a final step in the process of using GitHub App Commit Signing. We take our newly created tree and our new commit and we associate the two together. Once we add the commit to our newly formed tree our bot is going to see the GitHub App Installation Token, it will say "looks good to me" and then give us the seal of authenticity. To create this reference we need the SHA value for our new commit. To update a reference, curl the following endpoint Update a Reference remember to use the SHA value response from making your commit.

SHA - Response from the Create a Commit endpoint.

curl --no-progress-meter -X PATCH -H "Accept: application/vnd.github.v3+json" -H "Authorization: token ghs_T3ikErpqpHW6UB7Nh07P2GhtdnVjl81DstQR" https://api.github.com/repos/the-evil-corporation/repo-test555/git/refs/heads/main -d '{"sha": "478da5a33c21a22c84387b1602b90ddd0151efc8"}'

{
  "ref": "refs/heads/main",
  "node_id": "REF_kwDOH3Q4Eq9yZWZzL2hlYWRzL21haW4",
  "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/refs/heads/main",
  "object": {
    "sha": "478da5a33c21a22c84387b1602b90ddd0151efc8",
    "type": "commit",
    "url": "https://api.github.com/repos/the-evil-corporation/repo-test555/git/commits/478da5a33c21a22c84387b1602b90ddd0151efc8"
  }
}

Congratulations you have signed a commit using GitHub Commit Signing! You can check out more about GitHub Commit Signing here. To display verifcation statuses for all your commits, read About Vigilant Mode.

[terryhill89]

Great resources

[gabo-urrutia-inditex]

Okay this looks fantastic!! for an small file it works! but how do I sent a proper file, like for instance a YAML in the payload for creating a blob?
I have been struggling with that for hours :(

[joshjohanning]

@gabo-urrutia-inditex: I have a rough sample of this, but basically you have to escape newline and double quote characters.

code: https://github.com/joshjohanning-org/commit-sign-app/blob/main/.github/workflows/commit-sign.yml#L61-L64

[steini44as]

Hi @loujr , how can we use this when we don't control the commit? Like when using Lerna or Semantic Release for automatic versioning and changelog.md changes? This is done by the tool. We checkout the repo by using a token generated by a GitHub App, but how do we make those commits verified? Now we have added the GitHub App to the bypass list (because we force verified commits).

[noam-codefresh]

just to make it clear - the sha value you are sending on the 3rd step should have been 378b0bf1366719b46e9f9a2c99ef85676a8f985e from the 2nd step, right?

[BolajiOlajide]

Hello is it possible to push signed commit with a github app installation token using the git CLI?

I'll like to be able to run git push --force https://x-access-token:<INSTALLATION_ACCESS_TOKEN>@github.com/<OWNER>/<REPO_NAME> <COMMIT_SHA>:refs/heads/<branch_NAME> to push a signed commit

[joshjohanning]

No, you need to use the tree API to have it signed, unfortunately.

See my Actions workflow for another example: https://github.com/joshjohanning-org/commit-sign-app/blob/main/.github/workflows/commit-sign.yml#L80-L153

[BolajiOlajide]

Thank you very much.