Connecting to GitHub

Three steps are involved with connecting Merge Freeze to a protected branch in GitHub: Authorize Merge Freeze to access some of your details, Install the Merge Freeze App on your GitHub organization or personal account, and Add a protected branch so Merge Freeze knows which pull requests to monitor.

Info about required permissions

Authorize Merge Freeze

We use GitHub as the only method for authenticating who you are. We don’t use email/password combinations or any other method to sign you in. This is because we need to ask GitHub what repositories you belong to that also have the Merge Freeze App installed on them.

Install the Merge Freeze App

Merge Freeze is a GitHub App. GitHub Apps offer much more granular permissions than GitHub OAuth Apps and do not belong to any one user. They can be installed either on a whole organisation or only on specific repositories by anyone who is an owner or has admin rights.

Create a new project

Merge Freeze works by adding a status check to any pull request that wants to merge into a protected branch of your choosing, usually main. Once you have chosen a repository and a protected branch Merge Freeze will automatically send status updates to all pull requests wanting to merge into it (SUCCESS by default until you toggle your first merge freeze).

Who can implement a merge freeze?

After adding a project to your Merge Freeze dashboard, navigate to the Access Control tab.

From here, repository admins (as defined by GitHub Repository > Permissions > Admin) may select 1 of the following:

1. Only repository admins can freeze/unfreeze

2. Repository admins and members with "write" access can freeze/unfreeze

3. All users with repository access

If "Repository admins only" is selected, then only users with GitHub admin privileges on the project's repository can:

• implement a freeze or unfreeze via the web UI

• unfreeze or re-freeze a single pull requests

• unfreeze deployments (if the web API is being used in a deployments script)

If "Repository admins and write access members only" is checked, then only users with GitHub "write" privileges on the project's repository (including admins) can perform the above operations.

To implement the equivalent of "readonly" access, such that Github contributors with only "pull" permissions may access the Merge Freeze dashboard and read project statuses (but not API keys), simply check "Repository admins and write access members only."

By default, anyone who has access to a repository that has Merge Freeze installed on it will have the option to implement a merge freeze through the web UI. Here’s how GitHub defines access to a repository:

The authenticated user has explicit permission to access repositories they own, repositories where they are a collaborator, and repositories that they can access through an organization membership.

Further, if a project has been connected to Slack, then anyone in that Slack team can also implement a merge freeze using the /mergefreeze Slack command. This may be restricted separately inside Merge Freeze > Integrations > Slack. Learn more.

In addition to the Access Control settings inside your Merge Freeze dashboard, users must have GitHub admin privileges to the repository in order to add, update and delete recurring freezes; connect, disconnect and change the channel of a protected branch’s Slack notifications; and update a protected branch’s web API auth token.