github-app

gittuf/github-app

gittuf enables independently verifiable security policies to be defined for a repository. These policies rely on signed commits in Git and signed in-toto attestations.

What does this do?

The gittuf GitHub app is a helpful bridge between gittuf policies and GitHub's code review workflow for a pull request. For example, you may want a minimum number of code review approvals for a pull request to be merged. The GitHub app for gittuf allows using GitHub pull request reviews to satisfy gittuf policy requirements.

A public good version of this app is hosted for public github.com repositories. This is hosted via the Open Source Security Foundation (OpenSSF) where gittuf is an incubating project. Alternatively, you can deploy this app yourself for repositories hosted on github.com or on an on-premises GitHub enterprise instance.

The attestations recorded by the app for pull request approvals can also be used to meet the upcoming SLSA source track. However, as the source track is still under development, the attestations may evolve when SLSA requirements change.

How does the app work?

Once installed, the gittuf GitHub app monitors your repository for pull request and push events via GitHub webhooks. Whenever a user approves a pull request, the app records this information in the repository as a code review approval attestation. This attestation can be used to verify that the change meets gittuf policy. The app also adds a status check to pull requests that indicate whether the available approvals meet the configured gittuf policy.

NOTE: gittuf stores attestations in the repository in a custom Git reference (refs/gittuf/attestations). For the app to be able to push the attestation to this reference, it needs push permission to the repository.

Installation and Getting Started

To install the gittuf app on your repository, see the getting started documentation. It'll walk you through deciding how you'd like to deploy the app on your repository, and any additional steps that you'll need to take after installation.

Have Questions?

Feel free to reach out on the OpenSSF Slack if you have questions on how the app works, installation, or just want to say hi!