Deployments API

If you want to implement a complete code freeze it may not be enough to stop people merging into your protected branch on Github, you may want to block any deployments from happening in whatever software you use to push your code to production.

To achieve this we offer an endpoint for each protected branch that provides JSON formatted data about whether there is currently a merge freeze in place or not. By querying this endpoint you can add a condition in your deployment script to only continue if your protected branch is not frozen.

Before using the endpoint you must first generate an access token. You can do this by clicking “Generate an access token” in the Deployments API panel of a protected branch. These access tokens do not expire. If you feel that your access token has been compromised and you’d like to generate another one you can simply click “Regenerate” to create a new one. Please note, however, that your old access token will cease to work from that point onwards.

The HTTP method and url to get your protected branch’s Merge Freeze data is as follows: GET https://www.mergefreeze.com/api/branches/[Account or Organization name]/[Repository name]/[protected branch name]/?access_token=[Access token]

For example:GET https://www.mergefreeze.com/api/branches/mycompany/mywebsite/master/?access_token=123abc

The endpoint will return the following fields:

Field name

Data type

Description

branch

String

The name of the protected branch

repository

String

The full name (account + repository name) of the protected branch’s Github repository

frozen

Boolean

Whether or not there is currently a merge freeze in place

frozen_by

String or Null

The name of the person who implemented the merge freeze (may be “scheduled freeze” if a recurring freeze is responsible for the frozen state, or “slack user” if a Slack user has implemented a merge freeze but we don’t have their name). Will return null if there is no merge freeze currently in place.

For example:

{
"branch": "master",
"repository": "Team-FooBar/My-App",
"frozen": true,
"frozen_by": "John Wick"
}

Allow deployments but block merging

If you’d like to perform a deployment while still keeping a merge freeze in place you can click the “Allow deployments” button. This button only shows up if your branch is currently frozen and you have created an access token for the Deployments API (an indication that you may be using it).

Clicking this button will change the Deployments API response’s frozen field to false but the merge freeze will stay on in all other places, so your team members will not be able to merge into the protected branch.

This can be undone by clicking the “Undo” link.