From 4af7c245f4a7bd40933f682ea7c6e7a8013714aa Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Wed, 18 Nov 2026 02:10:26 +0000 Subject: [PATCH 1/2] docs: complete the GitLab CI and Bitbucket Pipelines guides Fetch the target branch so the rebase check (CC202) runs, and show how to check the merge or pull request title (--pr-title) and description (--ai-attribution-only), with GitLab's 2700-character description limit and Bitbucket's API read. --- docs/guides/other-ci.md | 62 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 61 insertions(+), 1 deletion(-) diff --git a/docs/guides/other-ci.md b/docs/guides/other-ci.md index d95a917..c79db19 100644 --- a/docs/guides/other-ci.md +++ b/docs/guides/other-ci.md @@ -22,7 +22,14 @@ example below handles both: Each job runs on merge or pull requests only, because the variables it reads exist only there. Add `--author-name --author-email` to the `commit-check` -call in the loop to check each commit's author as well. +call in the loop to check each commit's author as well, and `--files` to +check the files each commit adds (configured in the `[files]` section). + +The branch check (`--branch`) also covers `require_rebase_target` (CC202), +which needs the target branch in the clone. Neither GitLab nor Bitbucket +fetches it for a merge or pull request, so each job fetches it first. Without +it the rule reports itself as skipped (`rebase target 'main' not found`) and +the job passes. !!! note "On 2.18.2 or older" @@ -48,6 +55,8 @@ commit-check: - if: $CI_PIPELINE_SOURCE == "merge_request_event" script: - pip install commit-check + - target="$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" + - git fetch --quiet origin "+refs/heads/$target:refs/remotes/origin/$target" - commit-check --branch - | head="${CI_MERGE_REQUEST_SOURCE_BRANCH_SHA:-$CI_COMMIT_SHA}" @@ -60,6 +69,8 @@ commit-check: ``` - `GIT_DEPTH: "0"` turns shallow cloning off. +- A merge request pipeline fetches only the commit it runs on, so the job + fetches the target branch for the rebase check. - In a merged results pipeline, `HEAD` is a merge commit GitLab made, and `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA` names the merge request's own last commit. In a plain merge request pipeline that variable is empty and @@ -67,6 +78,31 @@ commit-check: - The `python` image ships with git. A `-slim` image does not, and needs it installed first. +### Merge request title and description + +GitLab passes both to the job, so they are piped in as they are. Add these +lines to the `script`: + +```yaml + - printf '%s\n' "$CI_MERGE_REQUEST_TITLE" | commit-check --pr-title + - printf '%s\n' "$CI_MERGE_REQUEST_DESCRIPTION" | commit-check --ai-attribution-only +``` + +- `--pr-title` checks the title with the message rules a one-line title can + meet: everything `--message` runs 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. +- `--ai-attribution-only` checks the description against your + `ai_attribution` policy, and, when `[pull_request] ai_declaration_checkboxes` + is set, that it ticks exactly one AI declaration box (CC501). GitLab task + lists (`- [x]`, `* [x]`, `1. [x]`) are read like GitHub's. +- GitLab cuts `CI_MERGE_REQUEST_DESCRIPTION` to its first 2700 characters + (`CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED` is then `true`). Put the AI + declaration boxes near the top of the merge request template, so a long + description does not cut them off. +- 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 ```yaml title="bitbucket-pipelines.yml" @@ -81,6 +117,8 @@ pipelines: depth: full script: - pip install commit-check + - target="$BITBUCKET_PR_DESTINATION_BRANCH" + - git fetch --quiet origin "+refs/heads/$target:refs/remotes/origin/$target" - commit-check --branch - | shas=$(git rev-list "$BITBUCKET_PR_DESTINATION_COMMIT..$BITBUCKET_COMMIT") || exit 1 @@ -95,6 +133,28 @@ pipelines: - Bitbucket merges the destination branch into the pull request before the step runs. The range stops 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. + +### Pull request title and description + +Bitbucket gives the step the pull request's id but not its title or +description, so the step reads them from the Bitbucket API. Create a +[repository access token](https://support.atlassian.com/bitbucket-cloud/docs/repository-access-tokens/) +with the **Pull requests: Read** scope, store it as a secured repository +variable named `PR_READ_TOKEN`, and add to the `script`: + +```yaml + - >- + curl -fsS -H "Authorization: Bearer $PR_READ_TOKEN" + "https://api.bitbucket.org/2.0/repositories/$BITBUCKET_REPO_FULL_NAME/pullrequests/$BITBUCKET_PR_ID" + -o pr.json + - python -c 'import json; print(json.load(open("pr.json"))["title"])' | commit-check --pr-title + - python -c 'import json; print(json.load(open("pr.json"))["description"])' | commit-check --ai-attribution-only +``` + +`--pr-title` and `--ai-attribution-only` work as in the +[GitLab section](#merge-request-title-and-description). Editing a pull +request does not start a pipeline, so run the step again after an edit. ## Azure Pipelines From 9a85b7f3049ed19d300e7f04bc43dc671da0337b Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Wed, 18 Nov 2026 02:16:33 +0000 Subject: [PATCH 2/2] docs: run the title and description checks before the commit loop The loop ends with exit, so lines added after it never ran. Also note the fork and rebase-target cases of the fetch, offer a guard for a description GitLab cut at 2700 characters, and read the Bitbucket fields in a step of their own so a failed read fails the step. --- docs/guides/other-ci.md | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/docs/guides/other-ci.md b/docs/guides/other-ci.md index c79db19..81d804c 100644 --- a/docs/guides/other-ci.md +++ b/docs/guides/other-ci.md @@ -29,7 +29,8 @@ The branch check (`--branch`) also covers `require_rebase_target` (CC202), which needs the target branch in the clone. Neither GitLab nor Bitbucket fetches it for a merge or pull request, so each job fetches it first. Without it the rule reports itself as skipped (`rebase target 'main' not found`) and -the job passes. +the job passes. The jobs fetch the request's target branch; if +`require_rebase_target` names a different branch, fetch that one instead. !!! note "On 2.18.2 or older" @@ -70,7 +71,10 @@ commit-check: - `GIT_DEPTH: "0"` turns shallow cloning off. - A merge request pipeline fetches only the commit it runs on, so the job - fetches the target branch for the rebase check. + fetches the target branch for the rebase check. A merge request from a fork + runs its pipeline in the fork, where `origin` is the fork: fetch from + `"$CI_MERGE_REQUEST_PROJECT_URL.git"` instead of `origin` there, so the + branch comes from the target project. - In a merged results pipeline, `HEAD` is a merge commit GitLab made, and `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA` names the merge request's own last commit. In a plain merge request pipeline that variable is empty and @@ -81,7 +85,7 @@ commit-check: ### Merge request title and description GitLab passes both to the job, so they are piped in as they are. Add these -lines to the `script`: +lines to the `script`, before the commit loop (its `exit` ends the script): ```yaml - printf '%s\n' "$CI_MERGE_REQUEST_TITLE" | commit-check --pr-title @@ -97,9 +101,15 @@ lines to the `script`: is set, that it ticks exactly one AI declaration box (CC501). GitLab task lists (`- [x]`, `* [x]`, `1. [x]`) are read like GitHub's. - GitLab cuts `CI_MERGE_REQUEST_DESCRIPTION` to its first 2700 characters - (`CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED` is then `true`). Put the AI - declaration boxes near the top of the merge request template, so a long - description does not cut them off. + (`CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED` is then `true`), so only that + part is checked. 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 + description check: + + ```yaml + - test "$CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED" != "true" || { echo "The description is over 2700 characters; GitLab passed only part of it"; exit 1; } + ``` - Editing the title or description does not start a pipeline. Run the pipeline again from the merge request's **Pipelines** tab after an edit. @@ -141,18 +151,25 @@ Bitbucket gives the step the pull request's id but not its title or description, so the step reads them from the Bitbucket API. Create a [repository access token](https://support.atlassian.com/bitbucket-cloud/docs/repository-access-tokens/) with the **Pull requests: Read** scope, store it as a secured repository -variable named `PR_READ_TOKEN`, and add to the `script`: +variable named `PR_READ_TOKEN`, and add to the `script`, before the commit +loop: ```yaml - >- curl -fsS -H "Authorization: Bearer $PR_READ_TOKEN" "https://api.bitbucket.org/2.0/repositories/$BITBUCKET_REPO_FULL_NAME/pullrequests/$BITBUCKET_PR_ID" -o pr.json - - python -c 'import json; print(json.load(open("pr.json"))["title"])' | commit-check --pr-title - - python -c 'import json; print(json.load(open("pr.json"))["description"])' | commit-check --ai-attribution-only + - >- + python -c 'import json; pr = json.load(open("pr.json")); + open("title.txt", "w").write(pr["title"]); + open("description.txt", "w").write(pr["description"])' + - commit-check --pr-title < title.txt + - commit-check --ai-attribution-only < description.txt ``` -`--pr-title` and `--ai-attribution-only` work as in the +Reading the fields in a step of their own makes a failed API read fail the +step, instead of piping empty text into the check. `--pr-title` and +`--ai-attribution-only` work as in the [GitLab section](#merge-request-title-and-description). Editing a pull request does not start a pipeline, so run the step again after an edit.