Frequently asked questions

What GitHub permissions does the app require?

Repository permissions

Administration: Read and write. This is so we can add and remove protected branch rules on a repository when the "Toggle a protected branch" freeze method is being used.

Metadata: Read-only. So we can see which repositories a user has access to.

Pull requests: Read-only. So we know which pull requests to send commit statuses to when using the "Update all pull requests" freeze method.

Commit statuses: Read and write. So we can update commit statuses to either success or failure when using the "Update all pull requests" freeze method.

We're not able to read or write to your repository's code base.

Organization permissions

Members: Read only. So we can determine a logged in user's role within an organization (an organization administrator has access to more settings in the Merge Freeze UI).

User authorization permissions

We don't ask for any extra permissions at the user level beyond what is required to login via GitHub.

Is self-hosted GitHub Enterprise supported?

Unfortunately we don’t yet support self-hosted GitHub Enterprise instances.

GitHub marketplace apps can’t be installed on self-hosted GitHub instances. Apps for these instances require a complex setup involving creating a new app on the self-hosted instance with all the same permissions and webhook configuration as the app found in the GitHub Marketplace.

The app’s code needs to be told the url of the self-hosted GitHub instance and is then run in either a container on the privately hosted machine, or it runs in the cloud (like the marketplace app) and is allowed to connect to the private server.

Both options involve complexity that we have decided not to undertake yet. We apologize to anyone who’s affected by this and hope to have a solution some time in the future.

When I try and subscribe to a paid plan all I see is “Unfortunately, invoiced customers cannot purchase paid plans on the GitHub Marketplace.”

When an invoiced GitHub account tries to sign up for a subscription to Merge Freeze via the GitHub marketplace they are sadly met with the following message: “Unfortunately, invoiced customers cannot purchase paid plans on the GitHub Marketplace.”

We offer payment via Stripe for these customers. To do this you’ll need to first sign up to the Open source plan (which is free). Then visit your Installation's management page by clicking the gear cog in the top left Organization dropdown picker of your Merge Freeze dashboard:

On this page you'll see the option to start a free trial via credit card or ACH in the bottom left of the Plans section:

After choosing a plan (Reactive or Proactive) you'll be able to add a payment method and begin a 14 day free trial.

If you prefer to pay annually for a discount, simply start a free trial on a monthly plan, then modify your plan when the Installation view refreshes. From this portal you may upgrade, downgrade, switch to annual billing, and download previous invoices.

How do I fix a pull request that has a Merge Freeze status check that’s stuck on pending?

If a pull request is created or updated in GitHub it will send Merge Freeze a webhook. Merge Freeze then tries to find the current status of the relevant project (frozen or unfrozen) and sends the pull request a status update via the GitHub API.

If a network error occurs so that the webhook never reaches Merge Freeze, or some other error occurs so that the status update doesn’t make it to GitHub then the Merge Freeze status can be left in a “pending” state with a message that says something like “Expected - Waiting for status to be received”.

To fix this you can either send an update to your pull request so that it triggers another webhook, or you can force Merge Freeze to send another status update to all open pull requests by toggling a freeze off and on again.

New commits can be made to a repository without having to make code changes using the --allow-empty flag e.g.

git commit --allow-empty -m "Trigger update"

Merge Freeze no longer updates the status of my pull request

It turns out that no single commit id can be given more than 1000 status updates from the same context (you can consider Merge Freeze to be a context). So if you have an old pull request that has been sitting there without any new commits it’s possible with many freezes and unfreezes that this limit is hit.

To fix this you’ll need to send a new commit to the pull request. New commits can be made to a repository without having to make code changes using the --allow-empty flag e.g.

git commit --allow-empty -m "Trigger update"

Why does it take so long for all PRs to get updated when freezing / unfreezing?

If you’re using the default “Push a status update to all PRs” method of freezing then every time a project is frozen or unfrozen we need to make an API call to every open pull request.

These updates must be done serially, according to GitHub app rules. If you have many open pull requests it may take some time to update them all (roughly one second per pull request).

If you have many pull requests that need updating you may wish to switch to the “Toggle a branch protection rule” method of freezing. This can be done in a project’s settings under “Freeze method.”

How come people can still merge even though I have frozen my project?

By default GitHub will still let you merge even when status checks fail:

To block merging completely: In your GitHub repository head to Settings -> Branches -> Protected branches and choose the branch that you'd like to be able to freeze (e.g. master).

  • Check Protect this branch.

  • Check Require status checks to pass before merging.

  • Under Status checks found in the last week for this repository check mergefreeze.

  • Optionally check Include administrators if you want admins to obey the rules too.

  • Click Save changes

Now when the branch is frozen users will not be able to merge:

Do I need to invite other users to my Merge Freeze project?

You don’t need to specifically invite users to your Merge Freeze project to allow them to freeze / unfreeze projects.

Merge Freeze uses GitHub permissions system to decide which projects a user should have access to. It does this by using the GitHub API to fetch all repositories that have the Merge Freeze app installed and that the user is a member of. These will automatically show in the user’s Merge Freeze control panel when they login.

I want to freeze / unfreeze all of my repositories at the same time

After many customer requests, we implemented a simple "batch freeze" feature in August 2022.

GitHub only allows one update per second for each open pull request, however, so using this may lead to long update times if you update all PRs in every repository of your organization.

For reasons stated above, please be careful with this feature. Alternatively, consider using the Merge Freeze API with an organization level access token to loop through each of your repos and freeze them 1 at a time programmatically, keeping in mind that a 1 req/sec rate-limit applies.

Last updated