Automated GitHub Access

There are many use cases where you will want to automate access or changes on GitHub, this page describes the options available to run that automation and to manage the authentication and authorisation.

The choice of automation mechanism is constrained based on how your automation is intended to be triggered and how integrated it needs to be be with divisional infrastructure

Automation mechanisms Usage notes
GitHub action - hosted in GitHub Can be scheduled or triggered from events within any repository
Hosted by GitHub and easy to setup
Access to divisional infrastructure is limited
More info: GitHub docs
GitHub action - self hosted Can also be scheduled or triggered from events within any repository
Unlike GitHub hosted actions, they run within divisional infrastructure
More info: GitHub docs
Webhook listener Repository level and organisation level activity in GitHub can trigger a call to an external webhook listener
These listeners need to be deployed on divisional infrastructure outside of GitHub
More info: GitHub docs
External processes External processes, including webhook listeners and self hosted GitHub action runners or fully independent external processes, running on divisional infrastructure can run and be triggered by GitHub activities as well as non-GitHub activities

All authorisation / authentication mechanisms are available to all automation mechanisms

Authentication / Authorisation mechanisms Usage notes
Personal access token Has the same access levels as a user or divisional ‘service account’, and any API calls made will appear to come from that specific user
It is discouraged to use this auth type
It is difficult to constrain the permissions to be the minimum necessary
It is associated strongly to a specific user, so is difficult to manage the responsibilities effectively across multiple people
More info: GitHub docs
GitHub App The preferred way to manage automation access across multiple repos in an organization or across multiple organizations
Fine grained control over what the app can do at the repository and organisation level
Application managers can be assigned to ensure it is managed by a team safely and effectively
Activities performed in GitHub will be labeled appropriately as [bot] activity performed by the named app
More info: GitHub docs
Deploy key Deploy keys are a public/private key pair, where the public key is attached to a repository in GitHub
This allows automation to read/pull the repository ( by default, although write/push access can be granted )
Gives git push/pull access and is not used to make GitHub API calls
Each key needs to be attached to each repository where it’s required
More info: GitHub docs