Skip to content

Commit 8f11eb4

Browse files
authored
docs: document commit-check-ci and name GitLab and Bitbucket on the homepage (#95)
1 parent 0325250 commit 8f11eb4

11 files changed

Lines changed: 170 additions & 121 deletions

File tree

‎docs/changelog.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ page that documents it.
1111

1212
| Version | What changed | Documented in |
1313
|---|---|---|
14+
| [2.23.0](#v2230) | `commit-check-ci` checks a whole merge or pull request in one GitLab CI job or Bitbucket Pipelines step | [GitLab CI, Bitbucket and Azure Pipelines](guides/other-ci.md) |
1415
| [2.22.0](#v2220) | `--pr-title` checks a pull or merge request title on any CI; the rebase check works in Bitbucket pull request steps and GitLab merged results pipelines | [GitLab CI, Bitbucket and Azure Pipelines](guides/other-ci.md#merge-request-title-and-description) · [CC202](rules.md#cc202) |
1516
| [2.21.1](#v2211) | Subject length rules leave out a squash merge's ` (#123)` and skip Dependabot and Renovate commits | [CC004](rules.md#cc004) · [CC005](rules.md#cc005) |
1617
| [2.21.0](#v2210) | A pull request description must tick one of its template's AI declaration checkboxes (opt-in) | [CC501](rules.md#cc501) · [Requiring the template's AI declaration](guides/policies.md#requiring-the-templates-ai-declaration) |
@@ -43,6 +44,16 @@ page that documents it.
4344
| [2.5.0](#v250) | Organization-wide config with `inherit_from` | [Across an organization](guides/organization.md) |
4445
| [2.0.0](#v200) | Configuration moved from YAML to TOML — breaking | [Migrating from v1](migration.md) |
4546

47+
## v2.23.0 (2026-11-19) { #v2230 }
48+
49+
### Added
50+
51+
* `commit-check-ci` checks the merge or pull request a GitLab CI job or Bitbucket Pipelines step runs for: the source branch and every commit the request adds, and with an option each the title, the description, the commits' authors and their files. ([GitLab CI, Bitbucket and Azure Pipelines](guides/other-ci.md), [#714](https://github.com/commit-check/commit-check/pull/714))
52+
53+
### Fixed
54+
55+
* A pull request title or description that fails is headed `Rejected by Commit Check`, not `Commit rejected`: neither is a commit. ([Requiring the template's AI declaration](guides/policies.md#requiring-the-templates-ai-declaration), [#713](https://github.com/commit-check/commit-check/pull/713))
56+
4657
## v2.22.0 (2026-11-18) { #v2220 }
4758

4859
### Added

‎docs/compare/tools.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ Replace the hook:
6565
```yaml title=".pre-commit-config.yaml"
6666
repos:
6767
- repo: https://github.com/commit-check/commit-check
68-
rev: v2.22.0
68+
rev: v2.23.0
6969
hooks:
7070
- id: check-message
7171
```

‎docs/configuration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -274,7 +274,7 @@ Used from a hook definition, with no config file anywhere in the repository:
274274
```yaml title=".pre-commit-config.yaml"
275275
repos:
276276
- repo: https://github.com/commit-check/commit-check
277-
rev: v2.22.0
277+
rev: v2.23.0
278278
hooks:
279279
- id: check-message
280280
args:

‎docs/example.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,7 @@ pushed:
186186
```yaml title=".pre-commit-config.yaml"
187187
repos:
188188
- repo: https://github.com/commit-check/commit-check
189-
rev: v2.22.0
189+
rev: v2.23.0
190190
hooks:
191191
- id: check-no-force-push
192192
stages: [pre-push]

‎docs/guides/integrations.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ developer sees locally and what is enforced on the pull request.
99
| [Pre-commit hook](pre-commit.md) | As the message is written | Yes — `--no-verify` | `.pre-commit-config.yaml` in each repository |
1010
| [GitHub Action](github-actions.md) | On every push and pull request, in CI | No | A workflow file in each repository |
1111
| [GitHub App](github-app.md) | On every push and pull request, hosted | No | Install once for the organization |
12-
| [GitLab CI, Bitbucket, Azure Pipelines](other-ci.md) | On every merge or pull request, in CI | No | A job in each repository's pipeline file |
12+
| [GitLab CI, Bitbucket Pipelines](other-ci.md) | On every merge or pull request, in CI | No | Two lines in each repository's pipeline file |
13+
| [Azure Pipelines, any other CI](other-ci.md#azure-pipelines) | On every pull request, in CI | No | A job in each repository's pipeline file |
1314
| [Command line](../example.md) | Wherever you call it: a range of commits, a CI you write yourself | — | `pip install commit-check` |
1415
| [MCP server](mcp.md) | Before the commit exists, inside an AI coding agent | — | One entry in the agent's MCP config |
1516
| [Python API](python-api.md) | Wherever your own code runs: a bot, a server-side hook, an agent you build | — | `pip install commit-check`, then `import commit_check.api` |
@@ -22,7 +23,8 @@ developer sees locally and what is enforced on the pull request.
2223
not after a CI round trip.
2324
- **A policy needs a check that cannot be skipped.** Anyone can pass
2425
`--no-verify` to a hook. The Action and the App run where that is not
25-
possible, and a required check keeps a violating change from merging.
26+
possible, and a required check keeps a violating change from merging. On
27+
GitLab and Bitbucket the pipeline job is that check.
2628
- **More than a handful of repositories wants one config.** `inherit_from`
2729
lets every repository share a base policy and override only what it
2830
genuinely needs, whichever of the above runs the checks.
@@ -65,6 +67,12 @@ ones created later, gets a **Commit Check** result on each commit of every
6567
push and pull request, with no workflow file and no CI minutes.
6668
[Set it up →](github-app.md)
6769

70+
## GitLab CI and Bitbucket Pipelines { #gitlab-ci-and-bitbucket-pipelines }
71+
72+
One job in the pipeline runs `commit-check-ci`, which finds the merge or pull
73+
request and checks its branch, every commit it adds and, if asked, its title
74+
and description. [Set it up →](other-ci.md)
75+
6876
## MCP server
6977

7078
The same rules as tools for an AI coding agent, so the message is right before

‎docs/guides/other-ci.md‎

Lines changed: 125 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,15 @@
11
# GitLab CI, Bitbucket and Azure Pipelines
22

3-
On GitHub, the [Action](github-actions.md) and the [App](github-app.md) do
4-
this work for you. Everywhere else Commit Check runs as one job in the
5-
pipeline: it is a Python package with no runtime dependencies, so any runner
6-
that can `pip install` can run it, and it reads the same `cchk.toml` as the
7-
hook and the Action.
3+
On GitHub, the [Action](github-actions.md) and the [App](github-app.md) check
4+
every pull request for you. On GitLab CI and Bitbucket Pipelines one command
5+
does that job: `commit-check-ci`, which comes with the package from 2.23.0
6+
on. It finds the merge or pull request from the variables the CI system sets
7+
and checks the source branch and every commit the request adds, against the
8+
same `cchk.toml` as the hook and the Action. The title, the description, each
9+
commit's author and the files it changes are one option away.
810

9-
Two things are different from running it on your own machine, and each
10-
example below handles both:
11-
12-
- **The checkout can be a detached HEAD**, as it is on GitLab and Azure, and
13-
then git has no branch to report. `commit-check --branch` reads the name
14-
from the CI's own variables instead, the merge or pull request's source
15-
branch first, so the jobs call it as is.
16-
- **A merge request has more than one commit.** `--rev` checks one commit, so
17-
the job loops over the commits the merge request adds, as in
18-
[Checking a range of commits](../example.md#checking-a-range-of-commits).
19-
The loop needs the history those commits sit on, so each example turns
20-
shallow cloning off. If the range cannot be read, the job fails rather than
21-
passing with nothing checked.
22-
23-
Each job runs on merge or pull requests only, because the variables it reads
24-
exist only there. Add `--author-name --author-email` to the `commit-check`
25-
call in the loop to check each commit's author as well, and `--files` to
26-
check the files each commit adds (configured in the `[files]` section).
27-
28-
The branch check (`--branch`) also covers `require_rebase_target` (CC202),
29-
which needs the target branch in the clone. Neither GitLab nor Bitbucket
30-
fetches it for a merge or pull request, so each job fetches it first. Without
31-
it the rule reports itself as skipped (`rebase target 'main' not found`) and
32-
the job passes. The jobs fetch the request's target branch; if
33-
`require_rebase_target` names a different branch, fetch that one instead.
34-
35-
!!! note "On 2.18.2 or older"
36-
37-
Releases before 2.18.3 read only GitHub's variables, so on a detached
38-
checkout `--branch` judges `HEAD`, which is always allowed, and passes
39-
whatever the branch is called. Pipe the name in instead: a value piped
40-
into `--branch` on its own is the name it checks.
41-
42-
```console
43-
$ echo "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" | commit-check --branch # GitLab
44-
$ echo "$BITBUCKET_BRANCH" | commit-check --branch # Bitbucket
45-
$ echo "${SYSTEM_PULLREQUEST_SOURCEBRANCH#refs/heads/}" | commit-check --branch # Azure
46-
```
11+
On Azure Pipelines, and on any other CI, the job is
12+
[written by hand](#azure-pipelines).
4713

4814
## GitLab CI
4915

@@ -56,32 +22,67 @@ commit-check:
5622
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
5723
script:
5824
- pip install commit-check
59-
- target="$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
60-
- git fetch --quiet origin "+refs/heads/$target:refs/remotes/origin/$target"
61-
- commit-check --branch
62-
- |
63-
head="${CI_MERGE_REQUEST_SOURCE_BRANCH_SHA:-$CI_COMMIT_SHA}"
64-
shas=$(git rev-list "$CI_MERGE_REQUEST_DIFF_BASE_SHA..$head") || exit 1
65-
status=0
66-
for sha in $shas; do
67-
commit-check --message --rev "$sha" --compact || status=1
68-
done
69-
exit $status
25+
- commit-check-ci
7026
```
7127
72-
- `GIT_DEPTH: "0"` turns shallow cloning off.
73-
- A merge request pipeline fetches only the commit it runs on, so the job
74-
fetches the target branch for the rebase check. A merge request from a fork
75-
runs its pipeline in the fork, where `origin` is the fork: fetch from
76-
`"$CI_MERGE_REQUEST_PROJECT_URL.git"` instead of `origin` there, so the
77-
branch comes from the target project.
78-
- In a merged results pipeline, `HEAD` is a merge commit GitLab made, and
79-
`CI_MERGE_REQUEST_SOURCE_BRANCH_SHA` names the merge request's own last
80-
commit. In a plain merge request pipeline that variable is empty and
81-
`CI_COMMIT_SHA` is that commit.
28+
Every check is listed under a heading of its own, and one failure fails the
29+
job:
30+
31+
```text
32+
$ commit-check-ci
33+
Branch
34+
passed
35+
Commit ccdfc043 added the login form
36+
✖ CC001 message failed: added the login form
37+
The commit message should follow Conventional Commits. See https://www.conventionalcommits.org
38+
Suggest: Use <type>(<scope>): <description>, where <type> is one of: feat, fix, docs, style, refactor, test, chore, perf, build, ci
39+
Docs: https://commit-check.com/rules/#cc001
40+
41+
Commit 20119d2e fix: trim the user name
42+
passed
43+
44+
1 of 3 failed.
45+
```
46+
47+
- `GIT_DEPTH: "0"` turns shallow cloning off, for this job only. The command
48+
needs every commit of the merge request and the commit they start from.
49+
With a clone that ends inside the merge request the job fails and names
50+
this setting, rather than pass with commits unchecked.
51+
- The command fetches the target branch itself, which
52+
`require_rebase_target` ([CC202](../rules.md#cc202)) compares with. For a
53+
merge request from a fork it fetches from the target project. A pipeline
54+
that runs in a fork of a private project cannot fetch it: with that rule
55+
set the branch check fails there, and without the rule the branch name is
56+
checked as usual.
57+
- In a merged results pipeline, `HEAD` is a merge commit GitLab made. The
58+
checks stop at the merge request's own last commit.
59+
- `rules` keeps the job to merge request pipelines. In any other pipeline the
60+
command checks the branch and the last commit only, and says so.
8261
- The `python` image ships with git. A `-slim` image does not, and needs it
8362
installed first.
8463

64+
### Options
65+
66+
Each check has an option, named after the
67+
[Action's input](github-actions.md#inputs) and on or off by default as it is
68+
there:
69+
70+
| Option | Default | What it checks |
71+
|---|---|---|
72+
| `--message` | on | The message of every commit the request adds. |
73+
| `--branch` | on | The name of the source branch, and `require_rebase_target` if it is set. |
74+
| `--author-name` | off | The author name of every commit. |
75+
| `--author-email` | off | The author email of every commit. |
76+
| `--files` | off | The files every commit changes, against the [`[files]` rules](../rules.md#push-rules). |
77+
| `--pr-title` | off | The title, with the message rules a one-line title can meet. |
78+
| `--pr-body-ai-attribution` | off | The description, against the AI attribution rules. |
79+
80+
An option alone switches its check on, and `=false` switches one off:
81+
82+
```yaml
83+
- commit-check-ci --author-email --branch=false
84+
```
85+
8586
### Making a failed check block the merge
8687
8788
Two things decide whether a failed check stops the merge request:
@@ -114,28 +115,26 @@ Two things decide whether a failed check stops the merge request:
114115

115116
### Merge request title and description
116117

117-
GitLab passes both to the job, so they are piped in as they are. Add these
118-
lines to the `script`, before the commit loop (its `exit` ends the script):
118+
GitLab passes both to the job, so two options are all it takes:
119119

120120
```yaml
121-
- printf '%s\n' "$CI_MERGE_REQUEST_TITLE" | commit-check --pr-title
122-
- printf '%s\n' "$CI_MERGE_REQUEST_DESCRIPTION" | commit-check --ai-attribution-only
121+
- commit-check-ci --pr-title --pr-body-ai-attribution
123122
```
124123

125124
- `--pr-title` checks the title with the message rules a one-line title can
126125
meet: everything `--message` runs except a body (CC011), a sign-off (CC012)
127126
and an AI author (CC017). With squash merges the title is often the commit
128-
message that lands.
129-
- `--ai-attribution-only` checks the description against your
127+
message that lands. A draft marker (`Draft:`, `[Draft]`, `(Draft)`) is not
128+
part of the title that is checked.
129+
- `--pr-body-ai-attribution` checks the description against your
130130
`ai_attribution` policy, and, when `[pull_request] ai_declaration_checkboxes`
131131
is set, that it ticks exactly one AI declaration box (CC501). GitLab task
132132
lists (`- [x]`, `* [x]`, `1. [x]`) are read like GitHub's.
133-
- GitLab cuts `CI_MERGE_REQUEST_DESCRIPTION` to its first 2700 characters
134-
(`CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED` is then `true`), so only that
135-
part is checked. Put the AI declaration boxes near the top of the merge
136-
request template, so a long description does not cut them off. To fail a
137-
description that was cut rather than check part of it, add before the
138-
description check:
133+
- GitLab passes a job only the first 2700 characters of a description, so
134+
only that part is checked, and the job says so when it happens. Put the AI
135+
declaration boxes near the top of the merge request template, so a long
136+
description does not cut them off. To fail a description that was cut
137+
rather than check part of it, add before the `commit-check-ci` line:
139138

140139
```yaml
141140
- test "$CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED" != "true" || { echo "The description is over 2700 characters; GitLab passed only part of it"; exit 1; }
@@ -158,54 +157,58 @@ pipelines:
158157
depth: full
159158
script:
160159
- pip install commit-check
161-
- target="$BITBUCKET_PR_DESTINATION_BRANCH"
162-
- git fetch --quiet origin "+refs/heads/$target:refs/remotes/origin/$target"
163-
- commit-check --branch
164-
- |
165-
shas=$(git rev-list "$BITBUCKET_PR_DESTINATION_COMMIT..$BITBUCKET_COMMIT") || exit 1
166-
status=0
167-
for sha in $shas; do
168-
commit-check --message --rev "$sha" --compact || status=1
169-
done
170-
exit $status
160+
- commit-check-ci
171161
```
172162

173-
- `depth: full` turns off the default clone depth of 50 commits.
163+
- `depth: full` gives the step the pull request's whole history. With a clone
164+
that ends inside the pull request the step fails and names this setting,
165+
rather than pass with commits unchecked.
174166
- Bitbucket merges the destination branch into the pull request before the
175-
step runs. The range stops at `BITBUCKET_COMMIT`, the pull request's own
167+
step runs. The checks stop at `BITBUCKET_COMMIT`, the pull request's own
176168
last commit, so commits that only came in with that merge are not checked.
177169
The rebase check judges that commit too, not the merge.
170+
- The output and the [options](#options) are the same as on GitLab.
178171

179172
### Pull request title and description
180173

181174
Bitbucket gives the step the pull request's id but not its title or
182-
description, so the step reads them from the Bitbucket API. Create a
175+
description, so the command reads them from the Bitbucket API. Create a
183176
[repository access token](https://support.atlassian.com/bitbucket-cloud/docs/repository-access-tokens/)
184177
with the **Pull requests: Read** scope, store it as a secured repository
185-
variable named `PR_READ_TOKEN`, and add to the `script`, before the commit
186-
loop:
178+
variable named `BITBUCKET_ACCESS_TOKEN`, and switch the two checks on:
187179

188180
```yaml
189-
- >-
190-
curl -fsS -H "Authorization: Bearer $PR_READ_TOKEN"
191-
"https://api.bitbucket.org/2.0/repositories/$BITBUCKET_REPO_FULL_NAME/pullrequests/$BITBUCKET_PR_ID"
192-
-o pr.json
193-
- >-
194-
python -c 'import json; pr = json.load(open("pr.json"));
195-
open("title.txt", "w").write(pr["title"]);
196-
open("description.txt", "w").write(pr["description"])'
197-
- commit-check --pr-title < title.txt
198-
- commit-check --ai-attribution-only < description.txt
181+
- commit-check-ci --pr-title --pr-body-ai-attribution
199182
```
200183

201-
Reading the fields in a step of their own makes a failed API read fail the
202-
step, instead of piping empty text into the check. `--pr-title` and
203-
`--ai-attribution-only` work as in the
184+
Without the variable, or with a token Bitbucket refuses, the two checks fail
185+
and say why: a title that could not be read is never checked as empty text.
186+
`--pr-title` and `--pr-body-ai-attribution` work as in the
204187
[GitLab section](#merge-request-title-and-description). Editing a pull
205188
request does not start a pipeline, so run the step again after an edit.
206189

207190
## Azure Pipelines
208191

192+
`commit-check-ci` knows GitLab's and Bitbucket's variables. Anywhere else it
193+
checks the branch and the last commit only, so on Azure Pipelines, or a CI of
194+
your own, the job calls `commit-check` itself. Commit Check is a Python
195+
package with no runtime dependencies: any runner that can `pip install` can
196+
run it.
197+
198+
Two things are different from running it on your own machine, and the
199+
example below handles both:
200+
201+
- **The checkout can be a detached HEAD**, as it is on Azure, and then git
202+
has no branch to report. `commit-check --branch` reads the name from the
203+
CI's own variables instead, the pull request's source branch first, so the
204+
job calls it as is.
205+
- **A pull request has more than one commit.** `--rev` checks one commit, so
206+
the job loops over the commits the pull request adds, as in
207+
[Checking a range of commits](../example.md#checking-a-range-of-commits).
208+
The loop needs the history those commits sit on, so the example turns
209+
shallow cloning off. If the range cannot be read, the job fails rather than
210+
passing with nothing checked.
211+
209212
```yaml title="azure-pipelines.yml"
210213
trigger: none
211214
@@ -250,3 +253,21 @@ steps:
250253
[build validation branch policy](https://learn.microsoft.com/en-us/azure/devops/repos/git/branch-policies#set-build-validation)
251254
on the target branch, and `System.PullRequest.SourceBranch` is only set for
252255
builds a branch policy started.
256+
- Add `--author-name --author-email` to the `commit-check` call in the loop
257+
to check each commit's author as well, and `--files` to check the files
258+
each commit adds (configured in the `[files]` section).
259+
- The branch check also covers `require_rebase_target` (CC202), which needs
260+
the target branch in the clone as `origin/<branch>`. Without it the rule
261+
reports itself as skipped (`rebase target 'main' not found`) and the job
262+
passes.
263+
264+
!!! note "On 2.18.2 or older"
265+
266+
Releases before 2.18.3 read only GitHub's variables, so on a detached
267+
checkout `--branch` judges `HEAD`, which is always allowed, and passes
268+
whatever the branch is called. Pipe the name in instead: a value piped
269+
into `--branch` on its own is the name it checks.
270+
271+
```console
272+
$ echo "${SYSTEM_PULLREQUEST_SOURCEBRANCH#refs/heads/}" | commit-check --branch
273+
```

0 commit comments

Comments
 (0)