How to Let Automation Bypass Required Reviews With a GitHub App

By Kaveh Alemi·Latchkey

Add the App to the bypass actors for the rule, then act with its token so required reviews stay on for people.

Required-review rules apply to every actor by default, including GITHUB_TOKEN. To let a specific automation proceed without weakening the rule, add the App to the rule's bypass list and use its installation token.

Steps

• Open the ruleset or branch protection rule and add the App as a bypass actor.
• Mint an App token with the needed write permission.
• Perform the merge or push with that token.

Workflow

steps:
  - uses: actions/create-github-app-token@v1
    id: app-token
    with:
      app-id: ${{ vars.APP_ID }}
      private-key: ${{ secrets.APP_PRIVATE_KEY }}
  - env:
      GH_TOKEN: ${{ steps.app-token.outputs.token }}
    run: gh pr merge ${{ github.event.pull_request.number }} --squash

Gotchas

• Bypass should be granted to the App only, never to all actors.
• Audit bypass usage; it is a powerful capability that skips human review.

Verify it actually works

A workflow that runs is not a workflow that works. Confirm the behaviour on a real event rather than on a manual dispatch, because trigger conditions, permissions, and context values all differ between the two.

# 1. validate the file before pushing
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color

# 2. trigger the real event, not workflow_dispatch
git commit --allow-empty -m "ci: verify trigger" && git push

# 3. watch it and read the conclusion, not just the colour
gh run watch
gh run view --log-failed

What usually goes wrong first

• The workflow file must exist on the default branch before scheduled or dispatch triggers appear at all.
• GITHUB_TOKEN permissions default to read-only in many organisations. Declare a permissions: block listing every scope the job needs.
• Fork pull requests get a read-only token and no access to secrets, regardless of workflow configuration.
• actions/checkout gives you depth 1 on a detached HEAD, so anything needing history or a branch name needs fetch-depth: 0.

Frequently asked questions

Related guides

References

• GitHub Actions documentation