A workflow can’t push to a protected branch with the default GITHUB_TOKEN. The token can’t go on a bypass list, and it never gets the admin role that skips branch protection by default. Instead, register your own GitHub App with Contents read and write, add it to the ruleset’s bypass list (or the push allowances of a classic branch protection rule), mint a token for it in the workflow with actions/create-github-app-token, and push with that. Anyone who can change the workflow can now push past your rules, so keep the bypass narrow.
Why can’t GITHUB_TOKEN push to a protected branch?
Per GitHub’s docs on the token, GITHUB_TOKEN is an installation access token for an app GitHub installs on your repository when Actions is on, and its permissions are limited to that repository. The permissions key in a workflow has no administration scope, so the most a workflow can ask for on code is contents: write, which is exactly the access branch protection restricts. Admins skip classic branch protection by default, but the token never becomes an admin.
The other way past protection is a bypass list, and the workflow token isn’t an actor you can add there. So you need a different identity: a GitHub App, or a personal access token stored as a secret.
Who can be a ruleset bypass actor?
In a ruleset you click Add bypass in the Bypass list section and pick actors. GitHub lists repository admins, organization owners and enterprise owners, the maintain or write role and custom roles based on it, teams, GitHub Apps, and Dependabot. The REST API also accepts deploy keys and individual users.
- Always allow is the default. The actor can push straight to the branch.
- For pull requests only makes the actor open a pull request, and then lets it merge past the rules. Deploy keys can’t use this mode.
- Exempt, in the REST API, doesn’t run the rules for that actor at all and writes no bypass audit entry.
Classic branch protection has two matching settings: Restrict who can push to matching branches, which takes people, teams or apps, and Allow specified actors to bypass required pull requests, which needs the repository to belong to an organization. If the two systems overlap on a branch, the stricter rule wins, which rulesets vs branch protection covers in detail.
How do I push to a protected branch from GitHub Actions?
- Register a GitHub App with Contents set to read and write, and install it on the repository.
- Store its client ID as an Actions variable and a private key as a secret, as the app-in-a-workflow guide shows. The client ID is not the app ID.
- Add the app to the ruleset’s bypass list, or to the classic rule’s push list.
- Mint a token in the job and hand it to checkout, so git pushes as the app:
- id: app-token
uses: actions/create-github-app-token@v3
with:
client-id: ${{ vars.APP_CLIENT_ID }}
private-key: ${{ secrets.APP_PRIVATE_KEY }}
- uses: actions/checkout@v5
with:
token: ${{ steps.app-token.outputs.token }}
- run: |
git commit -am "chore: bump version"
git pushWatch for loops. Events caused by GITHUB_TOKEN don’t start new workflow runs, but pushes made with the app token do. A release workflow that pushes to the branch it runs on will trigger itself, so filter on paths or on the commit author.
Why not use a personal access token?
It works, but the pushes then come from a person. To get them through a ruleset you’d add that person to the bypass list, which also lets them push past the rules from their own laptop, and when they leave the team the release job breaks with them. A GitHub App has neither problem.
What’s the security trade-off of a bypass actor?
The bypass belongs to the app, and anyone who can edit a workflow that mints the app’s token can use it. On a repo where every engineer has write access, that is every engineer, through a workflow change on any branch the app is allowed to run on. I’d treat workflow files that mint bypass tokens as protected code, put them under CODEOWNERS, and review them like any other infra change.
If the job only needs to land a version bump or a generated file, have the app open a pull request and give it “For pull requests only”. The change still skips the required review, but there’s a pull request to look at instead of a direct push. I wouldn’t use a deploy key here. GitHub’s deploy key docs say they never expire and outlive the person who added them, while an app’s installation token expires after an hour.
If the push still bounces with a rule error, the message names the rule that blocked it. Repository rule violations found walks through each one.
Frequently asked questions
Can I add GITHUB_TOKEN or github-actions to a ruleset bypass list?
Bypass actors are repository roles, teams, GitHub Apps and Dependabot, plus deploy keys and individual users through the API. The workflow token is not one you can name there, and it can never hold the admin role, since a workflow’s permissions top out at contents: write. Use your own GitHub App instead.
Does a push made with a GitHub App token trigger other workflows?
Yes. GitHub skips new workflow runs only for events the GITHUB_TOKEN causes, to stop recursive runs. A push made with a GitHub App installation token starts workflows like any other push, so guard against a workflow that pushes to the branch that triggers it.
Is a deploy key safer than a GitHub App for this?
Usually not. GitHub’s docs note that deploy keys never expire, are often stored without a passphrase, and stay active when the person who added them leaves. A deploy key with write access can do what an org member with admin access can do in that repository. An app’s installation token expires after an hour and carries only the permissions you gave the app.