---
title: "Set the scopes for a commit"
method: PUT
path: "/repos/{owner}/{repository}/commits/{sha}/scopes"
tags: ["pull_requests"]
---

# Set the scopes for a commit

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

Set the scopes a commit impacts.

Prefer this over the 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.

## Path parameters

- `sha` string, required — The commit SHA the scopes were computed from
- `owner` string, required — The owner of the repository
- `repository` string, required — The name of the repository

## Request body

- ScopesBody
  - `scopes` string[], required
  - `all_scopes` boolean

## Response `204`

Successful Response

## Other responses

- `403` — Forbidden
- `404` — Not found
- `409` — Conflict
- `422` — Unprocessable entity

## Changes

- **2026-09-14** `cb8f6b3b5d17` — 1 warning
  - the `scopes/items/` request property's maxLength was set to `1024`
- **2026-08-28** `b3864dcc206a` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/mergify/apis/mergify-api/changes/repos/:owner/:repository/commits/:sha/scopes/put.md)

---

[API](https://skmtc.dev/mergify/apis/mergify-api.md) · [All operations](https://skmtc.dev/mergify/apis/mergify-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mergify/apis/mergify-api/revisions/0414e6db380a?raw)