[Feature Request] Allow github actions to bypass branch protection rules in certain specific circumstances

[philomory]

There are workflows in which it is desirable to have the workflow itself make changes (such as updating a pom.xml, packages.json, CHANGELOG.md, etc.) on a branch which is otherwise protected from direct changes.

Some things that don't work (or don't work well):

• Simply disabling branch protection rules entirely for the branch in question isn't a feasible solution, because there are plenty of legitimate reasons to want branch protection rules in place.
• It's not possible to add the pseudo-user represented by the GITHUB_TOKEN to the "Restrict who can push to matching branches" list, but even if it were this wouldn't be a useful solution, because then any action from any branch could bypass the branch protection rules, making them too easily circumventable.
• You can create a "service user", add that service user to the "Restrict who can push to matching branches" list, create a Personal Access Token (PAT) for that service user, store the PAT in an environment secret, assign the relevant environment to your protected branch, and then have the workflow get the PAT from the environment, and then set up extra rules in all of your workflows triggerd by push events to make sure that they ignore any commits pushed by the service user (the way they'd ignore commits pushed using GITHUB_TOKEN). This more-or-less works, but it's a lot of work to replicate this set up across dozens of repositories, and it's really abusing a bunch of unrelated functionality for something that should be available out of the box.

My proposed solution is to add a checkbox under Branch Protection rules, "Allow Github Actions workflows run from matching branches to push commits back to the same branch". Checking this box would have two effects:

1. Workflows triggered by push events to the protected branch (which, given the branch is protected, will generally represent pull-request merges rather than remote pushes) will be allowed to push additional commits back to the protected branch as if they were being pushed by an individual user who was listed under "Restrict who can push to matching branches".
2. Workflows triggered by a workflow_dispatch event, where the workflow was dispatched from the protected branch (i.e. the workflow YAML file being executed is read from the protected branch) will be allowed to push additional commits back to the protected branch as if they were being pushed by an individual who was listed under "Restrict who can push to matching branches".

Note that in both cases, the workflow should only be permitted to push commits back to the same branch that the workflow is being executed from (or other, unprotected branches, as is already possible). A workflow should not be able to push commits to any other protected branch, not even a distinct branch that matches the same branch protection rule.

This feature request is inspired by a long-running discussion in the Github Community discussion boards; I felt it was worth bringing a concrete feature request to this Feedback repository, at this point.

NOTE: If you want to show your support for this feature request, please upvote it using the upvote button

rather than replying with a "+1". Replies like that just result in sending spam to everyone else interested in the issue, and importantly, don't even "count" when it comes to how much GitHub will prioritize the issue. They're just spam, they're not spam that also counts as a vote in any way.

[xakraz]

Also mentioned and requested here: https://github.community/t/allowing-github-actions-bot-to-push-to-protected-branch/16536

[brightshine1111]

Even though it wouldn't work in all use cases for all people, treating the github-actions bot as a full-fledged app so we can add it to protected branch pushers would be immensely useful in a number of situations.

E.g. at my company the main branch is gated by PRs; once a PR is merged that triggers the deploy workflow, and part of that workflow is simply pushing fast-forward commits to a minor version branch (e.g. if the current release should be v2.3.4, deploy will update the v2.3 branch to be even with main). We want to protect these minor versions branches so humans can't accidentally push to them and get them out of sync with main. The minor branches aren't critical to any other parts of our CI/CD pipeline otherwise, so simply being able to add the github-actions bot to that branch protection rule would be perfect in our situation.

[treeder]

This is the way.

Just let us add GitHub actions to this list:

[solarmosaic-kflorence]

FYI: https://github.blog/changelog/2022-05-17-consistently-allow-github-apps-as-exceptions-to-branch-protection-rules

[timothyjlaurent]

Thank you @daniel-res 👏 👏

This is the internet's only source for this information

[b3nk3]

I was able to add the App to the bypass list under branch protection with lesser permissions than @daniel-res.

Namely:

• Action
• PR
• Contents

[DoisKoh]

When I try to Allow specified actors to bypass required pull requests, I don't see any 'apps' to choose from. How do I allow GitHub actions to bypass this?

[christian-benseler-farm]

Same for me @DoisKoh

[air3ijai]

Did you previously install required app on your repository?

• https://github.com/<usernam>e/<repository>/settings/installations
• GitHub --> Repository --> Settings --> Integrations --> GitHub Apps
• Installing your own GitHub App

We use a own app for that and bellow is an example with a public one.

screenshots

[agaertner]

Just encountered this exact issue. This is certainly great to have for smaller hobby teams as well where you don't really want nor need to setup whole delivery pipelines.
I have setup simple automatic deployment on main which commits some changes like assembly version bumps, changelog, etc. However, I have to remove the branch protection for it to function which is bad for collaborations.

[Camuvingian]

Yes, GitHub, let's get this feature in please.

[cunhap]

Would also like this implemented. 👍

[israelboudoux]

That would be a great GA to implement!

[u-ways]

+1 I had to implement a walkaround to cater for such requirements which I do not encourage following...

Update: If you're very keen, you can see multiple ideas/solutions posted across the board linking to this issue.

[andreaagudo3]

how did you do it?

[maazmmd]

Can you please post the workaround

[madhifallah]

does this fit your need ? https://github.blog/changelog/2022-08-18-bypass-branch-protections-with-a-new-permission/

[dedece35]

+1 for our open-source organization (not GitHub Entreprise :( )

[philomory]

I don't think this fits the full need even for Github Enterprise customers. This is basically somewhere between non-solution number two and number three from the original post; that custom role can't be applied to the GITHUB_TOKEN psuedo-user, you have to assign it to an actual user; if you could assign it to the GITHUB_TOKEN psuedo-user, it wouldn't solve the problem acceptably because then anyone who could push to any branch, could push a workflow that interfered with protected branches; and if you instead assign the custom role to a "service account" user and make different service account users for workflows on different branches, well, that's non-solution number three: it works, more or less, but it's way too complicated to scale.

[frankinspace]

If you have an organization (on public github); you should be able to use the solution proposed in https://github.com/orgs/community/discussions/13836#discussioncomment-2901138

That's how we solved it; we have a custom dummy "CICD" github App and our workflows that make commits back to protected branches use the CICD github app credentials when committing. Then in the repository settings we allow the CICD App to skip status checks.

I still agree though it would be better if we didn't have to create our own app and we could just allow the GITHUB_TOKEN to skip status checks directly.

[philomory]

@frankinspace Doesn't that solution still fail in that someone could e.g. push a new workflow to a non-protected branch, that workflow would run with the credentials of the app, and could therefore push to a protected branch? Essentially meaning that the protected branch is not protected?

[frankinspace]

@philomory Yes, that is still a problem. IMO that's something I can tell my developers to not do. I still agree with your feature request and consider what I described an acceptable workaround until GH can resolve it properly.

[bigman73]

Also interested in a solution - I'm trying to auto bump the version but the branch protection rule I have on main branch doesn't allow it.

[Kav-K]

Also looking for a solution! I have a python-black formatter that pushes code to the main branch but the protection rules won't allow it

[airtonix]

in your case, you should do that on your PRs: do auto formatting commits to PRs only.

[thislooksfun]

I'm running into this issue as well. I use semantic-release to automatically update my package whenever my main branch is updated, and I use @semantic-release/git to commit the updated version and changelog back to the branch. However, I also want to enable required status checks so I can have that peace-of-mind (and also use auto-merge). But I can't, because if I turn it on the action can't push the version update anymore. Having a setting (either in the branch protection rules as suggested above, or in the action itself using the new permissions setting) would be a huge help for getting my setup clean and efficient.

[GuySartorelli]

+1 for this being part of the permissions in the workflow/action itself. There are some workflows where we want to be able to bypass branch protection rules - but we don't want to just blanket allow all workflows to bypass those protections.

[satonotdead]

Can we bypass the permission rules with Gitbook?

We are facing the same issue but within the same company (!)

[vagenas]

As a simplification of the "service user" approach outlined by the OP: for the commit(s) pushed by the "service user", one can consider using [skip ci] to suppress status checks without adding any extra rules in the workflows (see https://docs.github.com/en/actions/managing-workflow-runs/skipping-workflow-runs).

[bigman73]

As a simplification of approach number three, one can consider using [skip ci] in the respective commit message(s) to suppress status checks without adding extra rules in the workflows (see https://docs.github.com/en/actions/managing-workflow-runs/skipping-workflow-runs).

Not sure I'm following you. The idea is to have CI workflows run, not skipped, for example to auto increment versions.

[thislooksfun]

This isn't actually about getting workflows to run or not run at all, is about being able to have workflows push directly to a push-protected branch. [skip-ci] doesn't skip branch protection rules.

[vagenas]

I am referring to the third approach outlined by the OP, i.e. enabling pushing to the protected branch by explicitly allowing a "service user" to do so in the branch protection rules and then using the "service user" via a PAT accessed through an environment secret.

My comment was that, in this context, you do not necessarily have to (copying from the OP):

[...] set up extra rules in all of your workflows triggerd by push events to make sure that they ignore any commits pushed by the service user [...]

but you could rather just use [skip-ci] in those commits instead.

[ohmantics]

[skip ci] would work for the case mentioned above of @semantic-release/git trying to push release-related changes (package.json, CHANGELOG, etc.)

[sebaacuna]

So glad I read as far as your comment @vagenas , totally solved my issue where I already had the app (service account) set up but wanted a simple way to prevent the pushes to loop. Adding [skip ci] to the commit message saved the day.

[robertleeplummerjr]

Github, this is a need for full automation after deploys. PLEASE consider this soon.

[ramanpreetSinghKhinda]

+1

[iamfj]

+1

[suizman]

+1

[willcipriano]

Need this

[treyenelson]

I was able to work around this deficiency by using the Github App approach discussed above. I had never created an app before, so here is the list of steps that were necessary for anyone looking for something a bit more comprehensive:

• Follow the official guide to register an app and add the app id and private key to your repository's variables and secrets respectively: Making authenticated API requests with a GitHub App in a GitHub Actions workflow
• Configure your app with the following in the Permissions & events section (courtesy of @daniel-res)
  • Actions (read/write)
  • Administration (read/write)
  • Contents (read/write)
• Update your ruleset bypass list to include your Github App
• Obtain and use the app's token in your workflow. This is an abbreviated version of what I use for auto-incrementing my version number:

jobs:
  commit-version:
    steps:
    - uses: actions/create-github-app-token@v1
      id: app-token
      with:
        app-id: ${{ vars.YOUR_GITHUB_APP_ID }}
        private-key: ${{ secrets.YOUR_GITHUB_APP_PRIVATE_KEY }}
    - uses: actions/checkout@v4
      with:
        token: ${{ steps.app-token.outputs.token }}
    - id: increment-version
      run: |
        # ... run a script that increments the version
        #
        echo "VERSION=$(cat ./package.json | jq -r '.version')" >> $GITHUB_OUTPUT
    - uses: EndBug/add-and-commit@v9
      with:
        message: "Increment version to ${{ steps.increment-version.outputs.VERSION }} [skip ci]"

Note that this approach is not particularly secure and could be used to bypass the ruleset to commit arbitrary code by someone that has the ability to modify a workflow and trigger it in your repository.

[marengaz]

thanks for the instructions, have successfully followed them!

note: the following permissions are not necessary for the app to have, to successfully complete the above workflow:

• Actions (read/write)
• Administration (read/write)

[asos-danielc]

I just tested this but needed these 2 permissions still... could it be you do not have any checks specified in Require branches to be up to date before merging? I know when I didnt have any selected then it was fine, but when I added checks, it started failing, and adding the Administration permissions fixed it again.

It doesn't feel ideal at all, but it worked

[HiromiShikata]

@asos-danielc
Thank you very much!
It's very helpful for me and it works right now 🙇

For folks
I took much time because Do not allow bypassing the above settings on branch protection was enabled.
We need to disable Do not allow bypassing the above settings, please take care 🙏

[zack-pronto]

Thanks @treyenelson. I was able to follow these instructions as well and get this working. 🙏

[j05u3]

just for anyone: before being able to update the ruleset with the exception you need to install the app into the organization and repository

[pkozuchowski]

I'm not sure I understand. GitHub does not want to resolve this, because anyone would be able to deploy to protected branch by creating a workflow file (comment here @chrispat)

If I create a workaround with GitHub App or personal access token, what's stoping people from creating new workflow file and using my app/PAT to deploy maliciously to protected branches? The problem is still there, just a bit more limited.

I think it would be much safer, if there was a setting to allow only repository administrators to push any changes in .github folder. Then you wouldn't have to worry about malicious actors abusing workflows and the workflow bot could have more privileges.

[j616]

There are ways you can mitigate against this. Enable review of all 3rd party run requests. Or require an environment that requires review or locks to protected branches.

You could, of course, use a write-enabled deploy key and a Ruleset bypass. I believe in this case, that would act as a repo admin-level key. I believe this would behave in the way you are suggesting. But then you need to allow ALL admins to push to the branch in question. You cannot select deploy keys in repo Ruleset bypass settings. And bypass lists seem to be most-permissive, not least. So you can't do a combo of allowing Admin Always, and a team of human accounts For Pull Request Only to prevent the humans for pushing direct to the branch.

[sbellone]

You cannot select deploy keys in repo Ruleset bypass settings

I don't know since when, but this has changed now!
https://github.com/orgs/community/discussions/25305#discussioncomment-10728028

[adam-eichelkrautctpg]

For folks that wish to go down the service account PAT route, I found this helpful for authenticating our git command line:

  steps:
    - name: Checkout
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.YOUR_SECRET_TOKEN }}

The token configuration also configures your local git credentials, see https://github.com/actions/checkout

[oyamabsa]

+1

[sergiogomesan8]

+1

[ethaizone]

After I reviewed all the possible solutions provided, I found this one works fine:
https://github.com/orgs/community/discussions/25305#discussioncomment-8256560

I discovered it from this thread: https://github.com/orgs/community/discussions/25305

In my opinion, creating a GitHub App for the organization is better because I can customize the name and permissions. Once I have the App installed, I can make it appear only on specific repositories. The same applies to the App ID and private key, which I can also restrict to specific repositories.

Lastly, I can customize the App's logo, allowing us to have a beautiful logo for our bot.

[air3ijai]

That or similar solutions was described/discussed more that tree times already in that issue.

Maybe we should ask @philomory, to mention that workaround in the first post?

[ethaizone]

@air3ijai True. I think this thread is too long and I don't even aware that we had too many same discussion already.

[qoomon]

maybe my access token manager action is interesting for your use case as well https://github.com/qoomon/actions--access-token

[jmcdonagh]

kind of crazy this has been open for years now, often in actions you're doing CI work and updating branches. yea there are workarounds posted in here but there absolutely should be a checkbox for a built-in mechanism for github actions to bypass branch restrictions.

[kostrykin]

There now is the new Do not require status checks on creation option which finally solved this for me:
https://github.blog/changelog/2024-07-31-repository-updates-july-31st-2024/#avoid-required-status-checks-and-required-workflows-when-creating-branches

[j616]

This doesn't solve things in all cases, though. e.g. automated bumping of package version numbers on main.

[treeder]

This is the use case I need it for too.

[cwoodhayes]

+1 -- how is this still not implemented??

[GuySartorelli]

Please see this thread or for a tl;dr, the following from the main discussion description:

NOTE: If you want to show your support for this feature request, please upvote it using the upvote button rather than replying with a "+1". Replies like that just result in sending spam to everyone else interested in the issue, and importantly, don't even "count" when it comes to how much GitHub will prioritize the issue. They're just spam, they're not spam that also counts as a vote in any way.

[Bellangelo]

Another way to bypass protected branches is to create a pull request and auto-merge it. In case you have a minimum required reviewers rule then you can even approve the PR through the Github bot. If you have more than one required reviewer this won't work.

[GuySartorelli]

Branch protection rules go beyond just pushing commits. Pushing tags for example - you can't make a PR for a tag ;p

[so-jelly]

you sort of can, protect your tags so only actions can run it. pr a version file, once it is merged, actions does the tagging.

[glasser]

Er, really? I thought approving your own PR doesn't count.

[rwader-swi]

But auto-merge doesn't have option to be restricted for certain branches :(

[nyalsadiq]

Spent way too long trying to get this to work so will post my workaround here incase it helps anyone. I ended up creating a Github "app" which I was able to add to the bypass list on my ruleset. I configured my workflow to use the app following the README here, specifically this part and this part.

[sbellone]

Using Deploy keys is more straightforward: it doesn't require an App, and it permits to have a private key per repository instead of using the App's private key on multiple repositories: https://github.com/orgs/community/discussions/25305#discussioncomment-10728028