Some of the Guidelines can appear to be excessively disruptive to workflows. This page lists options and workarounds folks have found for some circumstances. Please add additional ones that you have used successfully! (It's a wiki!)

The first 2 sections list problems and options per guideline. If a guideline isn't listed, no one has (yet) had a problem. It's fair game to list a problem you actually have without a solution - other folks in the community may have ideas, even if they do not experience that particular problem. (No hypothetical problems though, please.)

Membership Guidelines

Repository Guidelines

The hosting organization should have 2FA set as a requirement.

Problem: That will kick a number of members & contributors from our org.

Yes, that is true. These days, very few people should be unable to establish a workable 2FA, so the question is how to perform the switch in the least disruptive manner. See GitHub/Converting to a "2FA required policy" for suggestions on that.

Problem: That breaks some of our automation, as the app can no longer log in with just a username and password.

GitHub lets you generate Personal Access Tokens (aka PAT, aka API token). See the GitHub PAT documentation for creating and using them.

Automation for sensitive apps should not rely on tokens generated from a personal account. See further notes for alternative suggestions.

Committing (or merging) to a production branch should be limited to the smallest reasonable set of people.

Problem: There is currently no way to grant a GitHub app permission to push to "limited commiters" branch.

GitHub is aware of the issue, but no firm date has been announced.

In the interim, the GitHub Apps can open PRs, but a human committer will need to merge them (or a bot using old style OAuth permissions).

Branch protection should be enabled for production branches

Enabling branch protection both (a) prevents branch deletion, and (b) dis-allows force pushes to the branch.

Problem: Our workflow uses force pushes to production to ensure we know what will be deployed.

There is another way to achieve the same goal, and make it easier for developers to update from production. The not well know "ours" merge strategy provides a way to achieve both:

• Ensuring the head contains exactly the files you need, and
• Allowing developers (and systems) to always apply Fast Forward updates.

An example of using this workflow is described on Stack Overflow.

Commits (including merges) to the production branch should be GPG signed.

Problem: Needing to setup GPG for use on GitHub might dissuade contributors

The guidance "require signed commits" only targets the production branch(es). Other branches (such as feature or topic branches) need not require signing. However, having unsigned commits in a branch means you need to handle merges in a certain way. In particular, you will not be able to rebase unsigned commits onto a production branch. You will need to merge ("squash-merge" is a GitHub feature that is incompatible with requiring signing).

One option:

• create a "feature branch", used only for merges (no signing required)
• create a "shadow branch", used only for merges (no signing required)
• whomever does the merge, merges via shadow branch using GitHub web UI:

Merging unsigned commits into signed-commits-required branch

Problem: I can't squash merge PRs generated by 3rd party services

This often occurs with dependency management tools, and is a known problem. The commits in the PR are signed, they just can't be included via any method that modifies that signed commit. Only the "merge" technique meets that requirement.

Problem: I can't use a bot to perform merges, when it uses the GitHub API to merge

This is a known problem. We're looking into workarounds, some of which require changes on the GitHub side.

IF you've had a bug opened about this guidance, please reach out to your security team for an appropriate workaround for your project.

General Notes

For tips that don't fit nicely above, please list them here.

GitHub web UI Challenges