On this page
GitLab CI, Bitbucket and Azure Pipelines¶
On GitHub, the Action and the App check
every pull request for you. On GitLab CI and Bitbucket Pipelines one command
does that job: commit-check-ci, which comes with the package from 2.23.0
on. It finds the merge or pull request from the variables the CI system sets
and checks the source branch and every commit the request adds, against the
same cchk.toml as the hook and the Action. The title, the description, each
commit's author and the files it changes are one option away.
On Azure Pipelines, and on any other CI, the job is written by hand.
GitLab CI¶
Every check is listed under a heading of its own, and one failure fails the job:
$ commit-check-ci
Branch
passed
Commit ccdfc043 added the login form
✖ CC001 message failed: added the login form
The commit message should follow Conventional Commits. See https://www.conventionalcommits.org
Suggest: Use <type>(<scope>): <description>, where <type> is one of: feat, fix, docs, style, refactor, test, chore, perf, build, ci
Docs: https://commit-check.com/rules/#cc001
Commit 20119d2e fix: trim the user name
passed
1 of 3 failed.
GIT_DEPTH: "0"turns shallow cloning off, for this job only. The command needs every commit of the merge request and the commit they start from. With a clone that ends inside the merge request the job fails and names this setting, rather than pass with commits unchecked.- The command fetches the target branch itself, which
require_rebase_target(CC202) compares with. For a merge request from a fork it fetches from the target project. A pipeline that runs in a fork of a private project cannot fetch it: with that rule set the branch check fails there, and without the rule the branch name is checked as usual. - In a merged results pipeline,
HEADis a merge commit GitLab made. The checks stop at the merge request's own last commit. ruleskeeps the job to merge request pipelines. In any other pipeline the command checks the branch and the last commit only, and says so.- The
pythonimage ships with git. A-slimimage does not, and needs it installed first.
Options¶
Each check has an option, named after the Action's input and on or off by default as it is there:
| Option | Default | What it checks |
|---|---|---|
--message |
on | The message of every commit the request adds. |
--branch |
on | The name of the source branch, and require_rebase_target if it is set. |
--author-name |
off | The author name of every commit. |
--author-email |
off | The author email of every commit. |
--files |
off | The files every commit changes, against the [files] rules. |
--pr-title |
off | The title, with the message rules a one-line title can meet. |
--pr-body-ai-attribution |
off | The description, against the AI attribution rules. |
An option alone switches its check on, and =false switches one off:
Making a failed check block the merge¶
Two things decide whether a failed check stops the merge request:
- Pipelines must succeed (Settings > Merge requests > Merge checks) is what makes a failed pipeline block the merge. Without it GitLab shows the failure and still lets the request merge.
-
Your other jobs have to run in the merge request pipeline too. Jobs with no
rulesof their own run in branch pipelines only, so GitLab starts a second pipeline for each merge request, with thecommit-checkjob alone in it. That pipeline is the one the merge request shows and the one Pipelines must succeed looks at: a failed test in the branch pipeline no longer blocks the merge. These rules start one pipeline for a merge request, and jobs with norulesrun in it:workflow: rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event" - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" when: never - if: $CI_COMMIT_BRANCH - if: $CI_COMMIT_TAGA job with
rulesof its own that only allow branch pipelines (if: $CI_COMMIT_BRANCH, for example) stays out of the merge request pipeline until its rules allowmerge_request_eventtoo. If your jobs already run in merge request pipelines, there is nothing to change.
Merge request title and description¶
GitLab passes both to the job, so two options are all it takes:
--pr-titlechecks the title with the message rules a one-line title can meet: everything--messageruns except a body (CC011), a sign-off (CC012) and an AI author (CC017). With squash merges the title is often the commit message that lands. A draft marker (Draft:,[Draft],(Draft)) is not part of the title that is checked.--pr-body-ai-attributionchecks the description against yourai_attributionpolicy, and, when[pull_request] ai_declaration_checkboxesis set, that it ticks exactly one AI declaration box (CC501). GitLab task lists (- [x],* [x],1. [x]) are read like GitHub's.-
GitLab passes a job only the first 2700 characters of a description, so only that part is checked, and the job says so when it happens. Put the AI declaration boxes near the top of the merge request template, so a long description does not cut them off. To fail a description that was cut rather than check part of it, add before the
commit-check-ciline: -
Editing the title or description does not start a pipeline. Run the pipeline again from the merge request's Pipelines tab after an edit.
Bitbucket Pipelines¶
depth: fullgives the step the pull request's whole history. With a clone that ends inside the pull request the step fails and names this setting, rather than pass with commits unchecked.- Bitbucket merges the destination branch into the pull request before the
step runs. The checks stop at
BITBUCKET_COMMIT, the pull request's own last commit, so commits that only came in with that merge are not checked. The rebase check judges that commit too, not the merge. - The output and the options are the same as on GitLab.
Pull request title and description¶
Bitbucket gives the step the pull request's id but not its title or
description, so the command reads them from the Bitbucket API. Create a
repository access token
with the Pull requests: Read scope, store it as a secured repository
variable named BITBUCKET_ACCESS_TOKEN, and switch the two checks on:
Without the variable, or with a token Bitbucket refuses, the two checks fail
and say why: a title that could not be read is never checked as empty text.
--pr-title and --pr-body-ai-attribution work as in the
GitLab section. Editing a pull
request does not start a pipeline, so run the step again after an edit.
Azure Pipelines¶
commit-check-ci knows GitLab's and Bitbucket's variables. Anywhere else it
checks the branch and the last commit only, so on Azure Pipelines, or a CI of
your own, the job calls commit-check itself. Commit Check is a Python
package with no runtime dependencies: any runner that can pip install can
run it.
Two things are different from running it on your own machine, and the example below handles both:
- The checkout can be a detached HEAD, as it is on Azure, and then git
has no branch to report.
commit-check --branchreads the name from the CI's own variables instead, the pull request's source branch first, so the job calls it as is. - A pull request has more than one commit.
--revchecks one commit, so the job loops over the commits the pull request adds, as in Checking a range of commits. The loop needs the history those commits sit on, so the example turns shallow cloning off. If the range cannot be read, the job fails rather than passing with nothing checked.
trigger: none
pr:
branches:
include: ["*"]
pool:
vmImage: ubuntu-latest
steps:
- checkout: self
fetchDepth: 0
- task: UsePythonVersion@0
inputs:
versionSpec: "3.13"
- script: pip install commit-check
displayName: Install Commit Check
- script: commit-check --branch
displayName: Check the branch name
- script: |
shas=$(git rev-list HEAD^1..HEAD^2) || exit 1
status=0
for sha in $shas; do
commit-check --message --rev "$sha" --compact || status=1
done
exit $status
displayName: Check the commit messages
trigger: nonekeeps the pipeline to pull requests; on a plain push there is no source branch to check and no merge commit to read the range from.fetchDepth: 0turns off shallow fetch, which new pipelines have on by default.- A pull request build checks out a merge commit whose first parent is the
target branch and second the pull request, so
HEAD^1..HEAD^2is exactly the commits the pull request adds. - The branch name comes from
System.PullRequest.SourceBranch, which isrefs/heads/feature/xin Azure Repos andfeature/xfor a GitHub repository. Commit Check drops therefs/heads/prefix itself. - In Azure Repos the
pr:section is ignored. Pull request builds come from a build validation branch policy on the target branch, andSystem.PullRequest.SourceBranchis only set for builds a branch policy started. - Add
--author-name --author-emailto thecommit-checkcall in the loop to check each commit's author as well, and--filesto check the files each commit adds (configured in the[files]section). - The branch check also covers
require_rebase_target(CC202), which needs the target branch in the clone asorigin/<branch>. Without it the rule reports itself as skipped (rebase target 'main' not found) and the job passes.
On 2.18.2 or older
Releases before 2.18.3 read only GitHub's variables, so on a detached
checkout --branch judges HEAD, which is always allowed, and passes
whatever the branch is called. Pipe the name in instead: a value piped
into --branch on its own is the name it checks.