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 of the Merge Freeze UI. Simply click your installation name in the top left account picker dropdown, followed by the gear cog icon.

GET freeze status

To implement a complete code freeze, it may not be enough to simply prevent merging into your protected branch on GitHub. You may also want to block deployments from happening in whatever software you use to push 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
branch	String	The name of the protected branch
repository	String	The full name (account + repository name) of the protected branch’s GitHub repository
note	String	A custom message provided by the team member who last froze the branch (if applicable).
allow_deployments	Boolean	Whether or not deployments are blocked; useful for "allow deployments" feature in Slack integration.
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.
unblocked_prs	Array	List of IDs of unblocked PRs (exceptions to an active freeze, that may be merged into the protected branch).
timezone	String	The timezone of this branch, set by the user who added this project to Merge Freeze (editable inside the UI).
next_freeze_at	Integer	Epoch timestamp of the next scheduled freeze (if applicable).
next_unfreeze_at	Integer	Epoch timestamp of the next scheduled freeze (if applicable).

For example:

{
  "branch": "master",
  "repository": "Team-FooBar/My-App",
  "note": "CI is down, freezing until it's sorted",
  "allow_deployments": false,
  "frozen": true,
  "frozen_by": "John Wick",
  "unblocked_prs": [325, 411],
  "timezone": "Eastern Time (US & Canada)",
  "next_freeze_at": 1666341060,
  "next_unfreeze_at": 1666357200  
}

GET freeze status errors/warnings

If you make a GET request to a branch or repository that does not exist, but your GitHub Account Name parameter + access token is valid, Merge Freeze will return an empty ( {} ) response. Note that this requires using an Organization-level access token, as branch-level access tokens for non-existing branches will not be recognized.

We added this functionality for customers needing to check if projects exist in their Merge Freeze account prior to creating them via API.

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:

Field name	Data type	Description
frozen	Boolean	true if you want the project to be frozen. false if you'd like the project to be unfrozen.
user_name	String	The name of the person implementing the change.
note	String	A reason for the freeze request. Does not work on "unfreezes." Note: GitHub interface only shows around 50 characters.

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.

POST freeze status 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.

Create branches (projects)

If your dev cycle involves switching between branch names on a per week or sprint basis, it can be cumbersome to recreate projects in the Merge Freeze UI.

With a simple API request you may instead set up (+ destroy) new projects remotely to save some time.

curl -d "account=merge-freeze&access_token=xxx&repository=core&branch=master&frozen=true" \
-X POST https://www.mergefreeze.com/api/branches

NOTE: as of Dec2023 this feature is in private beta. Email us your GitHub organization slug (e.g. /AcmeCo) to gain access.

Required body parameters:

Field name	Data type	Description
account	String	GitHub organization slug.
access_token	String	"Organization-wide" token; generate this on your Installation view (different from Branch API token - only account admins can see this UI).
repository	String	Repository slug on GitHub.
branch	String	Name of the branch. This can be changed later in the UI.

Optional body parameters:

Field name	Data type	Description
frozen	Boolean	Sets branch to frozen when true. Default false.
tz	String	E.g. UTC. Defaults to your most recently created branch's timezone.
generate_access_token	Boolean	Creates an API token for freezing/unfreezing this branch when true. Default false.
freeze_method	String	Can be "update_all_pull_requests" or "update_branch_protection_rule", defaults to update all pull requests.
admins_only	Boolean	Only admins can modify this branch when set to true. Default false.

Branch details (API token if requested, frozen status, etc) will be available in the response object.

Delete branches

Similar to creating branches via the API, this endpoint requires an organization level access token.

curl -d "account=merge-freeze&access_token=xxx&repository=core&branch=master" \
-X DELETE https://www.mergefreeze.com/api/branches

Required body parameters:

Field name	Data type	Description
account	String	GitHub organization slug.
access_token	String	"Organization-wide" token; generate this on your Installation view (different from Branch API token - only account admins can see this UI).
repository	String	Repository slug on GitHub.
branch	String	Name of the branch.

Create scheduled freezes

You may schedule one-off freezes/unfreezes for your projects via the API, as well as the scheduler user interface.

curl -d "access_token=xxx&account=merge-freeze&repository=core&branch=master\
&one_off_freeze_at=1662665219&one_off_unfreeze_at=1662924446" \
-X POST https://www.mergefreeze.com/api/scheduled_freezes

Required body parameters:

Field name	Data type	Description
account	String	GitHub organization slug.
access_token	String	"Organization-wide" token or Branch API token.
repository	String	Repository slug on GitHub.
branch	String	Name of the branch.
one_off_freeze_at	Integer	Epoch timestamp denoting when the freeze should begin.
one_off_unfreeze_at	Integer	Epoch timestamp denoting when the freeze should end.

Scheduling one-off freezes via the API across many projects at once may be useful for planning upcoming holidays and other events where deployment schedules will be impacted organization-wide.

List freeze logs

You may wish to programmatically analyze the freeze/unfreeze logs for an entire organization (installation's) repositories, or just 1 repository.

curl https://www.mergefreeze.com/api/freeze_logs?access_token=xxx&account=merge-freeze&repository=core

Required body parameters:

Field name	Data type	Description
account	String	GitHub organization slug.
access_token	String	"Organization-wide" token.

Optional body parameters:

Field name	Data type	Description
repository	String	Repository slug on GitHub.

Example reponse:

[
  {
    "id": 40257,
    "created_at": "2022-09-19 20:37:51 UTC",
    "action": "unfreeze",
    "branch_tz": "Eastern Time (US & Canada)",
    "context": "web",
    "branch": "master",
    "repository": "core",
    "note": null
  },
  {
    "id": 40256,
    "created_at": "2022-09-25 12:04:32 UTC",
    "action": "freeze",
    "branch_tz": "Eastern Time (US & Canada)",
    "context": "slack",
    "branch": "master",
    "repository": "mac-menu-plugin",
    "note": "awaiting approval by Xbar marketplace"
  }
]

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 to Merge Freeze 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.

Note that this limit is much higher than GitHub's rate limit, thus requests made with the intent to modify projects on GitHub should follow those limits instead of ours.

GitHub Security

Coming Soon - we are in the process of participating in GitHub's Secret Scanner program. This section will be updated with remediation steps when Merge Freeze's compatibility goes live.