Mergify

https://docs.mergify.com
Admin
Mergify helps teams ship code faster by providing CI insights, a robust merge queue, merge...
Tokens:636,900
Snippets:5,264
Trust Score:8.7
Update:7 hours ago
Show doc for...
Tokens:
Raw
### Example /setup/status response on a running install

Source: https://docs.mergify.com/enterprise/installation/

Once Mergify runs, every request gets only the mode and the overall result. The full report is public only while the install waits for setup. For details on a running install, use the console command or the dashboard.

```text
Mergify status: running
Overall: OK
```

--------------------------------

### Install and set up Mergify Stacks CLI

Source: https://docs.mergify.com/stacks/

Run these commands in a terminal to install the Mergify CLI, set up stacks, and push your branch. The setup guide provides the full walkthrough.

```bash
curl -fsSL https://raw.githubusercontent.com/Mergifyio/mergify-cli/main/install.sh | sh
mergify stack setup
mergify stack push
```

--------------------------------

### Install Mergify CLI and run stack setup

Source: https://docs.mergify.com/stacks/compare/gh-stack/

Installs the Mergify CLI via the one-line install.sh script and runs `mergify stack setup`, which adds a `commit-msg` hook that generates Change-Ids for commits.

```bash
curl -fsSL https://raw.githubusercontent.com/Mergifyio/mergify-cli/main/install.sh | sh
mergify stack setup
```

--------------------------------

### Get scheduled freezes - example response

Source: https://docs.mergify.com/api/scheduled-freeze/

Example response for the GET /repos/{owner}/{repository}/scheduled_freeze endpoint. Shows the structure of the scheduled_freezes array with id, reason, start, end, timezone, matching_conditions, and exclude_conditions fields. The start and end fields are date-time values, and matching_conditions and exclude_conditions can be null.

```json
{
  "scheduled_freezes": [
    {
      "id": "string",
      "reason": "string",
      "start": "2024-01-15T09:00:00Z",
      "end": "2024-01-15T09:00:00Z",
      "timezone": "string",
      "matching_conditions": null,
      "exclude_conditions": null
    }
  ]
}
```

--------------------------------

### Run Mergify Enterprise container with docker run

Source: https://docs.mergify.com/enterprise/installation/

Starts the Mergify Enterprise container in setup mode. Requires MERGIFYENGINE_DATABASE_URL, MERGIFYENGINE_REDIS_URL, MERGIFYENGINE_DATABASE_SECRET_CURRENT, and MERGIFYENGINE_BASE_URL. Add object storage variables if configured, and for GitHub Enterprise Server add MERGIFYENGINE_GITHUB_URL. If your GitHub server, PostgreSQL, or Redis uses a private CA, also add the options from Trusting a Private CA. The container serves the setup page until it holds both a GitHub App and a subscription token.

```bash
docker run \
  -d \
  --restart unless-stopped \
  -p 5000:5000 \
  --name mergify-engine \
  -e MERGIFYENGINE_DATABASE_URL=postgresql://postgres:password@postgres:5432/postgres \
  -e MERGIFYENGINE_REDIS_URL=redis://:password@my-redis:6379 \
  -e MERGIFYENGINE_DATABASE_SECRET_CURRENT=<the-key-you-generated> \
  -e MERGIFYENGINE_BASE_URL=https://mergify.mycompany.com \
  registry.mergify.com/enterprise:8.17.5
```

--------------------------------

### Query /setup/status as JSON and check the ok field

Source: https://docs.mergify.com/enterprise/installation/

Use this command to script the status check. `/setup/status` answers HTTP 200 whatever it finds, so a script should read the `ok` field of the JSON answer instead of relying on the HTTP status code. `jq -e .ok` exits with a non-zero status if the `ok` field is false.

```bash
curl -s -H 'Accept: application/json' https://mergify.mycompany.com/setup/status | jq -e .ok
```

--------------------------------

### Pull and run Mergify Enterprise Docker image

Source: https://docs.mergify.com/enterprise/maintenance/

Pulls the previously recorded version tag and starts the container with your environment variables. Use the same MERGIFYENGINE_DATABASE_SECRET_CURRENT as the original install; otherwise the setup page refuses to start because it cannot decrypt its configuration.

```bash
docker pull registry.mergify.com/enterprise:<version-tag>
# ... run docker run with your env vars ...
```

--------------------------------

### Example /setup/status plain HTTP response

Source: https://docs.mergify.com/enterprise/installation/

This is the output of `curl http://localhost:5000/setup/status` when the request bypasses the proxy. `Matches BASE_URL` is `FAIL` because the request did not go through the proxy; `Overall` only counts the connectivity checks.

```text
Mergify status: setup
Overall: OK

Request
  BASE_URL:           https://mergify.mycompany.com
  Request URL:        http://localhost:5000/setup/status
  Scheme:             http
  Host:               localhost:5000
  X-Forwarded-Proto:  (not set)
  X-Forwarded-For:    (not set)
  X-Forwarded-Host:   (not set)
  Matches BASE_URL:   FAIL

Connectivity
  Postgres            OK
  Redis               OK
  Subscription        OK  https://subscription.mergify.com
  GitHub              OK  https://github.com
```

--------------------------------

### Expected commit message with Change-Id trailer

Source: https://docs.mergify.com/stacks/setup/

Example output showing the Change-Id trailer appended to the commit message by the commit-msg hook.

```text
test: verify stack setup

Change-Id: Ia1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
```

--------------------------------

### Expected startup log output

Source: https://docs.mergify.com/enterprise/installation/

Expected log lines after the container starts, without timestamps. Indicates the database schema was applied, the worker and web server started, and the container is waiting for setup because no GitHub App or subscription token is present yet.

```text
Database schema updated
Started process PID=17 → mergify-engine worker
Started process PID=18 → mergify-engine web
waiting for setup: no GitHub App or no subscription token yet
```

--------------------------------

### Example Response for GET /repos/{owner}/{repository}/stats/ci_runs

Source: https://docs.mergify.com/api/statistics/

Shows the JSON structure returned on a successful 200 response. The response contains groups with base_ref, queue_name, and started, succeeded, and wasted interval arrays.

```json
{
  "groups": [
    {
      "base_ref": "string",
      "queue_name": "string",
      "started": null,
      "succeeded": null,
      "wasted": null
    }
  ]
}
```

--------------------------------

### Example /setup/status output before proxy

Source: https://docs.mergify.com/enterprise/installation.md

Shows the status report when the request bypasses the proxy. Matches BASE_URL is FAIL because the request URL does not match the configured BASE_URL; Overall only counts the connectivity checks.

```text
Mergify status: setup
Overall: OK

Request
  BASE_URL:           https://mergify.mycompany.com
  Request URL:        http://localhost:5000/setup/status
  Scheme:             http
  Host:               localhost:5000
  X-Forwarded-Proto:  (not set)
  X-Forwarded-For:    (not set)
  X-Forwarded-Host:   (not set)
  Matches BASE_URL:   FAIL

Connectivity
  Postgres            OK
  Redis               OK
  Subscription        OK  https://subscription.mergify.com
  GitHub              OK  https://github.com

```

--------------------------------

### Example Response for GET /repos/{owner}/{repository}/stats/batch_bisection

Source: https://docs.mergify.com/api/statistics/

Shows the JSON structure returned on a successful 200 response. The response contains 'started' and 'completed' arrays, each with base_ref, queue_name, priority_rule_name, and stats fields.

```json
{
  "started": [
    {
      "base_ref": "string",
      "queue_name": "string",
      "priority_rule_name": "string",
      "stats": null
    }
  ],
  "completed": [
    {
      "base_ref": "string",
      "queue_name": "string",
      "priority_rule_name": "string",
      "stats": null
    }
  ]
}
```

--------------------------------

### Example Response for CI Queue Stats

Source: https://docs.mergify.com/api/ci-insights/

Shows the JSON structure returned by the GET /ci/{owner}/queue/stats/{stat} endpoint. The response includes the requested stat, a summary value, and an array of time-bucketed values with start and end timestamps.

```json
{
  "stat": "total_jobs",
  "value": 0,
  "value_over_time": [
    {
      "start": "2024-01-15T09:00:00Z",
      "end": "2024-01-15T09:00:00Z",
      "value": 0
    }
  ]
}
```

--------------------------------

### Verify Mergify CLI installation with mergify --version

Source: https://docs.mergify.com/stacks/agents.md

Run after installing mergify-cli to confirm the CLI is available.

```bash
mergify --version
```

--------------------------------

### Install Mergify CLI in GitHub Actions

Source: https://docs.mergify.com/cli/usage/

Use the `Mergifyio/setup-cli` action to install the prebuilt `mergify` binary in a GitHub Actions workflow. It verifies the release checksum and adds the binary to `PATH`. By default it installs a pinned version; set `mergify_cli_version` to `latest` for the newest release. The action exposes the installed version as the `mergify_cli_version` output.

```yaml
- uses: Mergifyio/setup-cli@v1.3.0
- run: mergify --version
```

```yaml
- uses: Mergifyio/setup-cli@v1.3.0
  id: setup-cli
  with:
    mergify_cli_version: latest

- run: echo "Installed mergify-cli ${{ steps.setup-cli.outputs.mergify_cli_version }}"
```

--------------------------------

### Get queue checks retries stats - Example Request

Source: https://docs.mergify.com/api/statistics/

Example curl request for GET /repos/{owner}/{repository}/stats/checks_retries. Uses Bearer token authentication.

```bash
curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/stats/checks_retries" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Get base refs branches stats - Example Request

Source: https://docs.mergify.com/api/statistics/

Example curl request for GET /repos/{owner}/{repository}/stats/branches. Uses Bearer token authentication.

```bash
curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/stats/branches" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Check Mergify Enterprise container logs

Source: https://docs.mergify.com/enterprise/installation/

Displays the container logs to verify startup. The container applies the database schema, then starts the web server and a worker. The output shows lines like 'Database schema updated', 'Started process PID=17 → mergify-engine worker', 'Started process PID=18 → mergify-engine web', and 'waiting for setup: no GitHub App or no subscription token yet'.

```bash
docker logs mergify-engine
```

--------------------------------

### GET /default_products/{owner} - Example Response

Source: https://docs.mergify.com/api/products/

Example JSON response for the GET /default_products/{owner} endpoint, showing a products array with ci_insights. This is the expected successful response body.

```json
{
  "products": [
    "ci_insights"
  ]
}
```

--------------------------------

### Example output of connectivity-check

Source: https://docs.mergify.com/enterprise/troubleshooting/

Sample output from the connectivity-check command. Shows each check reporting ok, failure, or skipped, with a reason when present.

```text
redis: ok
postgres: ok
object_storage: skipped
> Object Storage is not configured
github_server: ok
```
Tokens:
Raw