Web API
Availability
The Web API can be used on any public repository that has been set up in Merge Freeze, or private repositories if your account subscribes to the Proactive plan.
Access tokens
Before using the API you must first generate an access token. 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.
There are two types of access tokens:
Project specific access tokens
Project specific access tokens only let you get information or freeze / unfreeze the project that relates to that specific access token. They can be generated in the Web API panel of each project.
Organization access tokens (organizations only)
Organization access tokens can get information or freeze / unfreeze any project that has been set up in Merge Freeze and belongs to your organization. To generate these access tokens your Github account must be an organization (not an individual) and you must be an administrator of the organization.
Assuming you meet the above criteria you'll find the organization access token in your organization settings in the Merge Freeze UI.
GET freeze status
If you want to implement a complete code freeze it may not be enough to simply stop people merging into your protected branch on Github, you may also 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 project 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.
The HTTP method and url to get your protected branch’s Merge Freeze data is as follows:
GET https://www.mergefreeze.com/api/branches/[Github account name]/[Github repository name]/[protected branch name]/?access_token=[Access token] The exact url for your project can be found in the "Web API" panel of your project.
The endpoint will return the following fields:
Field name
Data type
Description
branchString
The name of the protected branch
repositoryString
The full name (account + repository name) of the protected branch’s Github repository
frozenBoolean
Whether or not there is currently a merge freeze in place
frozen_byString 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:
1
{
2
"branch": "master",
3
"repository": "Team-FooBar/My-App",
4
"frozen": true,
5
"frozen_by": "John Wick"
6
}
Copied!
POST freeze status
In certain situations you may also want to programmatically freeze or unfreeze a branch. This can be done via the following endpoint:
POST https://www.mergefreeze.com/api/branches/[Github account name]/[Github repository name]/[protected branch name]/?access_token=[Access token]You must also send the following parameters either by including them as json in the body of the request or as form data:
Param name
Data type
Description
frozenBoolean
true if you want the project to be frozen.false if you'd like the project to be unfrozen.user_nameString
The name of the person implementing the change.
The exact url for your project and an example using curl can be found in the "Web API" panel of your project.
This endpoint will return the same fields as the "GET freeze status" endpoint above.
Errors/warnings
If a required parameter is missing or invalid you will receive an HTTP 400 status with a json payload containing an
error field describing the error.If you attempt to freeze a project that is already frozen (or unfreeze an unfrozen project) the change will not take place but you will still receive an HTTP 200 status, although you will receive a
warning field in the response describing the warning in addition to the normal fields returned in a successful response. 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 Web API (an indication that you may be using it).
Clicking this button will change the Web 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.
Rate limits
To prevent abuse requests are restricted to 100 per minute. Any requests exceeding this threshold will return a 429 error code and a
RateLimit-Reset header with a time stamp indicating when the rate limit time period will be reset.Last modified 2mo ago