Secure a GitHub organization in layers
Your source code, your secrets, and your deployment pipeline are all in one GitHub organization. This guide shows how to secure GitHub in layers: identity, network, repositories, tokens, and CI. Each step says when it needs GitHub Enterprise Cloud.
People reach GitHub from one address
The Client sends traffic for GitHub through a Gateway that has a fixed public IP.
The IP allow list accepts that address
The organization accepts connections from the Gateway address, which is on its IP allow list.
A stolen token fails from other places
A person at a different address cannot reach the private repositories, even with a valid credential.
CI reaches private systems by a tunnel
A workflow starts a headless Client and reaches the staging database. The database has no public endpoint.
Start with identity
Most attacks on a code host start with a stolen password or a stolen token. The first steps to secure a GitHub organization are thus about identity.
Require two-factor authentication
An organization owner can require GitHub two-factor authentication for each member and each outside collaborator. Turn this setting on first. Ask people to use a passkey, a security key, or an authenticator app, because these methods are stronger than SMS codes.
Add SAML single sign-on
With SAML single sign-on, a member must also sign in with your identity provider to reach the resources of the organization. When a person leaves the company, you suspend one account in the identity provider. SAML single sign-on needs GitHub Enterprise Cloud.
With SAML single sign-on on, a member must authorize each personal access token and each SSH key for the organization. A token that nobody authorized cannot read your repositories.
Review who is an owner
An owner can change each setting in this guide. Keep the number of owners small, and never have only one. Read the audit log of the organization regularly to see changes to members and settings.
Limit where connections come from
Identity controls say who a person is. A network control adds a second question: where the connection comes from.
The GitHub IP allow list lets an owner name the IP addresses that can reach the private resources of the organization. The list applies to the website, the API, and Git. An entry is one address or a range in CIDR notation. The feature needs GitHub Enterprise Cloud. The GitHub documentation gives the steps.
With the list on, a stolen token is of no use from an address that is not on the list.
Where the IP allow list is difficult
- Remote people have addresses that change. A list of home addresses is soon out of date. The team needs one fixed address to leave from.
- Integrations and runners also connect. Check how the list applies to your GitHub Apps and your GitHub Actions runners before you turn it on. The GitHub documentation describes each case.
- A mistake can lock you out. Add the addresses first, test them, and then turn on enforcement.
Protect branches, and give the least privilege
Use rulesets or branch protection
A ruleset or a branch protection rule controls how code gets into an important branch. For the default branch of each repository, set these rules:
- Require a pull request, with one or more approvals.
- Require the status checks to pass before a merge.
- Block force pushes and branch deletion.
An organization ruleset can apply the same rules to many repositories. The plan of the organization decides which of these features are available for private repositories.
Give teams the least privilege
GitHub has five repository roles: read, triage, write, maintain, and admin. Give access to teams, not to individual people, and give each team the lowest role that lets it do its work.
- Set the base permission of the organization to a low level, so that a new member does not get write access to all repositories.
- Keep the admin role for a small number of people.
- Review outside collaborators regularly, and remove the ones who no longer work with you.
Keep secrets out of code, and make tokens small
Turn on secret scanning and push protection
Secret scanning searches a repository for known types of credentials, such as cloud keys and API tokens. Push protection goes one step further. It blocks a push that contains a supported secret, before the secret gets into the history.
The two features are free for public repositories. For private repositories, they are part of a paid GitHub security product. When secret scanning finds a secret, revoke the secret first. A commit that deletes the secret does not remove it from the history.
Use fine-grained personal access tokens
A classic personal access token can frequently reach each repository that its owner can reach. Fine-grained personal access tokens are narrower:
- Each token works for the repositories that you select.
- Each token has only the permissions that you select, such as read access to contents.
- Each token has an expiration date.
An organization owner can require approval for fine-grained personal access tokens, and can restrict classic tokens. For automation, a GitHub App is frequently a better choice than a token that belongs to a person.
Secure GitHub Actions and its runners
A CI pipeline runs code with access to secrets. Treat each workflow as production software.
Give the GITHUB_TOKEN the least privilege
Each workflow run gets a temporary token named GITHUB_TOKEN. Set the default permission of this token to read-only in the organization settings. Then give each workflow only the permissions that it needs, with the permissions key in the workflow file. For example, contents: read is sufficient for a job that only runs tests.
Decrease the long-lived secrets
Use OpenID Connect to get short-lived credentials from your cloud provider, so that no cloud key stays in the repository secrets. Pin each third-party action to a full commit SHA, because a tag can move.
Decide how runners reach private infrastructure
Integration tests frequently need a staging database, an internal API, or a private package registry. Teams usually select one of three methods:
- A public endpoint. The staging system gets a public address. This method is easy, and it exposes the system to the internet.
- A self-hosted runner inside the network. The runner has direct access, but you must maintain it. GitHub recommends that you do not use self-hosted runners with public repositories.
- A tunnel from the runner. A hosted runner opens an encrypted tunnel to the private network for the time of the job. The private system stays private.
How Firezone adds the network layer
Firezone is an open source zero trust network access platform built on WireGuard. It helps with the two network problems in this guide. All other steps use settings in GitHub.
A fixed address for the IP allow list
Deploy a Firezone Gateway with a fixed public IP, and add a DNS Resource for *.github.com. Write a Policy that names the Group of people who work in the organization. Then add the Gateway address to the GitHub IP allow list.
The Client on each laptop now sends traffic for GitHub through the Gateway. Only people with a Policy can reach the organization, from any network. All other traffic uses the normal path of the device. The SaaS access guide gives each step.
Use two or more Gateways, and add each address to the list. One Gateway is one point of failure for access to your code.
Private Resources for GitHub Actions
A workflow can reach private systems with no public endpoint:
- Create a service account and a token in Firezone.
- Add the service account to a Group, and write a Policy for the one Resource that the workflow needs.
- Store the token as a secret in the repository.
- Start the headless Linux Client in the first step of the job.
The staging database or the package registry stays in the private network. The Gateway makes only outbound connections, so you open no inbound port for CI. The GitHub Actions guide has a complete workflow file.
Three levels of network control for a GitHub organization
The identity steps in this guide apply in each column. The table compares only the network layer.
| No network control | Office IP on the allow list | Firezone | |
|---|---|---|---|
| A stolen token is refused from an unknown address | No | Yes | Yes |
| Works for people outside the office | Yes | PartialOnly through the office VPN | YesThrough the closest Gateway |
| Rule for who can use the permitted address | No | PartialAll people on the office network | YesOne Policy for each Group |
| Only GitHub traffic takes the route | YesNo route | PartialOnly with split tunnel | YesOne DNS Resource |
| More than one exit address | No | PartialOne for each office | YesOne for each Gateway |
| CI reaches private systems with no public endpoint | No | PartialWith a self-hosted runner | YesHeadless Client and a service account |
The table describes the usual result of each approach. The GitHub IP allow list needs GitHub Enterprise Cloud. Read the GitHub documentation before you turn it on.
Common questions
What is the first step to secure a GitHub organization?
Require two-factor authentication for all members and outside collaborators. This one setting stops most attacks that use a stolen password. Then decrease the number of owners, and add SAML single sign-on if your plan includes it.
Does the GitHub IP allow list need GitHub Enterprise Cloud?
Yes. The IP allow list for an organization is a feature of GitHub Enterprise Cloud. SAML single sign-on for an organization also needs GitHub Enterprise Cloud.
How do remote developers work with a GitHub IP allow list?
Their traffic for GitHub must leave from an address on the list. Send that traffic through an office VPN or through a gateway with a fixed public IP. A Firezone Gateway does this for the GitHub traffic only.
Is a fine-grained personal access token safer than a classic token?
Usually, yes. A fine-grained token works only for the repositories and the permissions that you select, and it has an expiration date. If the token leaks, the attacker can reach much less.
How can GitHub Actions reach a private database?
There are three methods: a public endpoint, a self-hosted runner inside the network, or a tunnel from the runner. With Firezone, a workflow starts the headless Client with a service account token and reaches the database through a Gateway.