gh-pages branch protection rules in conflict with PR merge rules

[hlapp]

The gh-pages branch is under a branch protection rule that requires changes to come through a PR. I don't know whether this had been active for some time, but the most recent PR merge (#15), which must have used a squash merge, wasn't honored as satisfying the branch protection rule, resulting in a build failure.

I suspect that this gh-pages branch protection rule is a problem if allowing squash and rebase merges, but maybe this needs to be investigated.

I've for this time bypassed the issue by disabling the branch protection, re-triggering the previously failed Github Action, and then re-enabling branch protection.

[egrace479]

Yes, it seems like maybe I didn't need to create one for gh-pages, though I did exempt deploy keys (or do we need to create a deploy key?).

[egrace479]

When we figure this out, we should also update the guide on this topic.

[hlapp]

It seems like the API key automatically made available within GitHub Actions doesn't count as a deploy key.

It could be that we could create a deploy key and then add it as a secret to the environment for the GitHub Action. However, that also sounds to me like adding one security risk to circumvent another security tie-down.

[egrace479]

I think another option would be to use the repo admin override (since it did show me as deploying). I don't recall us having this issue with classic branch protections (we still have access to those, so that could be another option). I asked @wang2989 to look into this.

[egrace479]

Discussing more today, we may not have had this issue with the classic branch protections because those gh-pages branches were being updated by a PR directly to them, while here we are submitting the PR to main which triggers a deployment.

@wang2989 is going to summarize the options discussed with some resources.

[wang2989]

General Info

Summary of Issue: Current Ci/CD workflow involves pushing new commits to main via pull requests which then trigger a GitHub actions workflow and then builds an updated MKDocs site, pushing that to the gh-pages branch. GitHub pages is set to publish off the gh-pages branch. PRs made this way will fail during the push to the gh-pages branch as GitHub will flag that commits made this way are not through a PR (which is defined in the branch rulesets).

Main Focus of Solutions: Finding a way to allow pull requests to deploy to main without triggering/violating the GitHub rule set protecting the gh-pages branch.

Solutions

Option 1: Create a GitHub App and allow it to bypass the branch protection

• User Post Outlining Method
• Essentially defining the imageomics-guide repo as a GitHub App via an authentication token (the app installation token) and allowing GitHub Apps to bypass the commit rule set via adding it as a bypass
• Benefits: Will allow for current workflow to remain with the addition of generating the app tokens as needed, recommended method by GitHub on their blog, previously detailed implementation available
• Cons: Potential security risk allowing GitHub Apps as a whole to bypass the ruleset (unsure if able to specify specific GitHub apps), requires generation of secret keys so additional security risk, somewhat complicated

Option 2: Bypass branch protection using deploy key

• Generates a deploy key that is stored on the deployment environment so that any workflow being run in the environment can use the key and bypass the rule sets
• Benefits: Supported method by peaceiris , easy to implement and maintain
• Cons: Potential security risk cause of need to generate keys and keep safe, may need to separate rule sets so that environment does not bypass every rule

Option 3: Configure deployment workflow to use an admin-privilege bot account that is set to bypass branch protection

• User Post Outlining Method
• Current workflow in peaceiris/actions-gh-pages (the package used to build and push updated site to gh-pages) uses the user credentials of whoever made the pull request to main in order to authenticate and perform git commands. Can be configured to use an account that is explicitly allowed to bypass a branch rule so that all git commands during the workflow can run
• Benefits: Can be done through minimal setup and configuration of workflow, no need to generate deploy keys or app install tokens, bot account can be further used for more deployments/niche cases
• Cons: Similar security risks to previous 2 options, maintenance of bot account needed, credentials need to be safely stored, potentially creating an admin-level account just for this workflow issue

Additional Options (Requires more work / Not as seamless):

• Reconfiguring actions workflow to open a PR request instead of directly committing
• Try reverting to classic branch protections and seeing if workflow passes
• Add admin-level accounts to bypass rule (will only work if admin account makes PR)