Pull Requests

Push scopes and other per-pull-request data to Mergify.

Set the scopes for a pull request (deprecated) #

PUT /repos/{owner}/{repository}/pulls/{number}/scopes

Deprecated

Deprecated, and removed in a future release: use `PUT /repos/{owner}/{repository}/commits/{sha}/scopes` with the pull request's head SHA instead. `mergify ci scopes-send` sends it from CLI 2026.9.10.1 on; on a CI it cannot read the pull request and its head from, such as Jenkins, pass `--pull-request` and `--head-sha`. This addresses the scopes by pull request number alone, so the report cannot say which revision it was computed for, and the last one to arrive wins whatever head that was. A scope name may hold anything except a NUL byte or an unpaired UTF-16 surrogate, neither of which Postgres can store, and is limited to 1024 characters; a report carries at most 10000 of them. A report that breaks any of these is refused in full with a 422 and nothing is stored, so the pull request keeps whatever was reported for it last. A pull request number below 1, which GitHub never assigns, is refused the same way.

Authorization

CI Application Key

Path Parameters

number integer required

The pull request number

min: 1 · max: 9223372036854776000

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Request Body

scopesstring[]required

all_scopesboolean

Responses

204 Successful Response

403 `CI_TOKEN_SCOPES_TARGET_REFUSED`: The request is authenticated with the Mergify CI token of a job, which reports scopes only for the commit the job runs on, or for the pull request it tests.

detailstringrequired

Enum: CI_ADMIN_ROLE_REQUIRED CI_ID_TOKEN_AUDIENCE_REFUSED CI_ID_TOKEN_EXCHANGE_NOT_ENABLED CI_ID_TOKEN_EXPIRED CI_ID_TOKEN_INVALID CI_ID_TOKEN_ISSUER_REFUSED CI_ID_TOKEN_ISSUER_UNAVAILABLE CI_ID_TOKEN_NO_MATCHING_TRUST_POLICY CI_ID_TOKEN_NO_TRUST_POLICY CI_ID_TOKEN_REPOSITORY_NOT_INSTALLED CI_TOKEN_SCOPES_TARGET_REFUSED CI_TRACES_UPLOAD_UNUSABLE CI_TRUST_POLICY_NAME_TAKEN COMMAND_RESTRICTED CONFIGURATION_BRANCH_REFUSED CONFIGURATION_INVALID CONFIGURATION_REFUSED_BY_REPOSITORY_RULES CONFIGURATION_SIGNED_COMMITS_REQUIRED DEFAULT_BRANCH_NOT_FOUND GITHUB_ACCOUNT_SUSPENDED GITHUB_APP_ACCESS_LOST GITHUB_RATE_LIMITED GITHUB_UPSTREAM_REQUEST_FORBIDDEN GITHUB_UPSTREAM_REQUEST_REJECTED GITHUB_UPSTREAM_UNAVAILABLE ID_TOKEN_KEY_ROTATION_REFUSED INTEGRATION_NOT_CONFIGURED IP_ALLOW_LIST_NOT_CONFIGURED MERGE_QUEUE_DISABLED MERGE_QUEUE_SETTING_INVALID_BRANCH_PATTERN MERGE_QUEUE_SETTING_NOT_AVAILABLE NO_LOGIN_IN_PROGRESS ORGANIZATION_MEMBERS_ONLY PIPELINE_NAME_TAKEN PIPELINE_NOT_FOUND PIPELINE_RUN_NOT_FOUND PIPELINE_SECRETS_KEY_ALREADY_ADDED PIPELINE_SECRETS_KEY_IN_USE PIPELINE_SECRETS_KEY_LIMIT_REACHED PIPELINE_SECRETS_KEY_NOT_ACTIVE PIPELINE_SECRETS_KEY_NOT_FOUND PIPELINE_SECRETS_KEY_REPORTED PIPELINE_SECRET_LIMIT_REACHED PIPELINE_SECRET_NAME_TAKEN PIPELINE_SECRET_NOT_FOUND PIPELINE_SECRET_NOT_SEALED_TO_ACTIVE_KEYS PIPELINE_SECRET_VERSION_CHANGED PULL_REQUEST_ALREADY_QUEUED PULL_REQUEST_NOT_FOUND PULL_REQUEST_NOT_QUEUEABLE PULL_REQUEST_NOT_QUEUED RETRY_RULE_NOT_FOUND SAML_ENFORCEMENT_NOT_AUTHORIZED SETTING_MANAGED_BY_ENV SETUP_ALREADY_DONE SETUP_TOKEN_MISMATCH SUBSCRIPTION_API_UNAVAILABLE SUBSCRIPTION_INACTIVE SUBSCRIPTION_TOKEN_INVALID TEST_ALREADY_QUARANTINED TEST_BRANCH_NOT_TRACKED TEST_RETRY_NOT_CONFIGURED TEST_STATE_OVERLAP

documentation_urlstring

Example Response

                          {
  "detail": "string",
  "error_code": "CI_ADMIN_ROLE_REQUIRED",
  "documentation_url": "string"
}

404 Not found

409 Conflict

422 Unprocessable entity

Example Request

curl -X PUT "https://api.mergify.com/v1/repos/:owner/:repository/pulls/:number/scopes" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "scopes": [
    "string"
  ],
  "all_scopes": false
}'

Set the scopes for a pull request, POST variant (deprecated) #

POST /repos/{owner}/{repository}/pulls/{number}/scopes

Deprecated

Authorization

CI Application Key

Path Parameters

number integer required

The pull request number

min: 1 · max: 9223372036854776000

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Request Body

scopesstring[]required

all_scopesboolean

Responses

204 Successful Response

403 `CI_TOKEN_SCOPES_TARGET_REFUSED`: The request is authenticated with the Mergify CI token of a job, which reports scopes only for the commit the job runs on, or for the pull request it tests.

detailstringrequired

documentation_urlstring

Example Response

                          {
  "detail": "string",
  "error_code": "CI_ADMIN_ROLE_REQUIRED",
  "documentation_url": "string"
}

404 Not found

409 Conflict

422 Unprocessable entity

Example Request

curl -X POST "https://api.mergify.com/v1/repos/:owner/:repository/pulls/:number/scopes" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "scopes": [
    "string"
  ],
  "all_scopes": false
}'

Set the scopes for a commit #

PUT /repos/{owner}/{repository}/commits/{sha}/scopes

Set the scopes a commit impacts. This replaces the deprecated pull request variant. Scopes computed for one revision do not describe another, so naming the revision lets a report be matched against the head a pull request actually has. A report for a revision a pull request has already moved past can no longer overwrite what its current head reported; a report *is* still applied to every **open** pull request whose head it currently is, which is the normal case. A report replaces the previous one for that revision in full: `all_scopes` defaults to `false`, so omitting it clears a barrier previously reported for the same commit. Send the complete result of your scope computation every time. Send the pull request's head SHA (`github.event.pull_request.head.sha`). That is not always the revision your job checked out: on a `pull_request` event the default checkout is a merge commit, and a report keyed on that SHA matches no pull request head. A scope name may hold anything except a NUL byte or an unpaired UTF-16 surrogate, neither of which Postgres can store, and is limited to 1024 characters; a report carries at most 10000 of them. A report that breaks any of these is refused in full with a 422 and nothing is stored, so the pull request keeps whatever was reported for it last.

Authorization

CI Application Key

Path Parameters

sha string required

The commit SHA the scopes were computed from

pattern: ^[0-9a-fA-F]{40}$

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

repository string required

The name of the repository

min length: 1 · max length: 100 · pattern: ^[\w\-\.]+$

Request Body

scopesstring[]required

all_scopesboolean

Responses

204 Successful Response

403 `CI_TOKEN_SCOPES_TARGET_REFUSED`: The request is authenticated with the Mergify CI token of a job, which reports scopes only for the commit the job runs on, or for the pull request it tests.

detailstringrequired

documentation_urlstring

Example Response

                          {
  "detail": "string",
  "error_code": "CI_ADMIN_ROLE_REQUIRED",
  "documentation_url": "string"
}

404 Not found

409 Conflict

422 Unprocessable entity

Example Request

curl -X PUT "https://api.mergify.com/v1/repos/:owner/:repository/commits/:sha/scopes" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "scopes": [
    "string"
  ],
  "all_scopes": false
}'

Was this page helpful?