From b675eed7fbab1dc0f41388d6072c65c16af372de Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Tue, 10 Nov 2026 07:57:16 +0000 Subject: [PATCH] docs: add a page about Gitea, Forgejo and GitLab support List how the git server is detected, which token is read, which feedback features work on each server, and the differences to GitHub. --- cspell.config.yml | 1 + docs/docs/git-servers.md | 138 +++++++++++++++++++++++++++++++++++++++ docs/mkdocs.yml | 1 + 3 files changed, 140 insertions(+) create mode 100644 docs/docs/git-servers.md diff --git a/cspell.config.yml b/cspell.config.yml index 1a9c7f2a..f9431dcb 100644 --- a/cspell.config.yml +++ b/cspell.config.yml @@ -40,6 +40,7 @@ words: - Falsey - flate - fontawesome + - forgejo - gitea - gitmodules - gnueabi diff --git a/docs/docs/git-servers.md b/docs/docs/git-servers.md new file mode 100644 index 00000000..a553415d --- /dev/null +++ b/docs/docs/git-servers.md @@ -0,0 +1,138 @@ +# Supported Git Servers + +[git-bot-feedback]: https://crates.io/crates/git-bot-feedback +[gitlab-permissions]: https://github.com/2bndy5/git-bot-feedback/blob/main/docs/permissions/gitlab.md +[gitlab-masked-vars]: https://docs.gitlab.com/ci/variables/#mask-a-cicd-variable +[gitlab-mr-pipelines]: https://docs.gitlab.com/ci/pipelines/merge_request_pipelines/ +[forgejo-runner]: https://forgejo.org/docs/latest/admin/actions/ + +[quick-start]: index.md#quick-start +[thread-comments]: cli.md#-t-thread-comments +[pr-review]: cli.md#-p-pr-review +[passive-reviews]: cli.md#-r-passive-reviews +[no-lgtm]: cli.md#-g-no-lgtm +[file-annotations]: cli.md#-a-file-annotations +[step-summary]: cli.md#-w-step-summary +[lines-changed-only]: cli.md#-l-lines-changed-only +[files-changed-only]: cli.md#-f-files-changed-only +[diff-base]: cli.md#-b-diff-base + +cpp-linter is not limited to GitHub. It detects the git server from the environment variables that +the CI runner sets, and uses [git-bot-feedback][] to talk to the server's REST API. + +| The CI runner sets | Git server | Token is read from | +|---|---|---| +| `GITHUB_ACTIONS=true` | GitHub | `GITHUB_TOKEN` | +| `GITEA_ACTIONS=true` | Gitea | `GITEA_TOKEN` | +| `FORGEJO_ACTIONS=true` | Forgejo | `GITEA_TOKEN`, or `FORGEJO_TOKEN` (set by Forgejo's runner) | +| `GITLAB_CI=true` | GitLab | `GITLAB_TOKEN` | +| none of the above | none (local) | not used | + +Gitea and Forgejo runners also set `GITHUB_ACTIONS=true`, so they are checked first. + +Without a known CI environment, cpp-linter runs locally. The list of changed files then comes from +`git diff` (see [`--diff-base`][diff-base]), and nothing is posted to a server. + +## What works where + +| Feature | GitHub | Gitea and Forgejo | GitLab | +|---|---|---|---| +| Changed files of a pull request ([`--lines-changed-only`][lines-changed-only], [`--files-changed-only`][files-changed-only]) | yes | yes | yes (merge request) | +| Changed files of a push | yes | yes | yes | +| [`--thread-comments`][thread-comments] on a pull request | yes | yes | yes (merge request) | +| [`--thread-comments`][thread-comments] on a commit (push) | yes | no | no | +| [`--pr-review`][pr-review] | yes | yes | yes | +| [`--file-annotations`][file-annotations] | yes | highlighted lines in the job's log | no | +| [`--step-summary`][step-summary] | yes | appended to the file named by `GITHUB_STEP_SUMMARY` | no | +| Output variables (`checks-failed` and others) | yes | yes | printed in the log only | +| Collapsed groups in the log | yes | yes | yes | + +On every server, feedback is only posted to pull requests from a branch in the same repository. +For a pull request from a fork, cpp-linter still analyzes the changed files, but it skips the thread +comment and the review. + +## Gitea + +Use cpp-linter in Gitea Actions like in GitHub Actions. The differences are: + +- The token must be in `GITEA_TOKEN`. `GITHUB_TOKEN` is not read on Gitea. Without a token, + posting a thread comment or a review fails the run. +- Thread comments are only posted for pull requests, not for commits. +- Only a repository admin can dismiss a review. When the problems of an earlier review are fixed, + cpp-linter tries to dismiss that review. With the token that Gitea creates for a job, this fails + with `Must be repo admin` in the log, and the review that requested changes stays. To avoid a + stale blocking review, use [`--no-lgtm=false`][no-lgtm] (cpp-linter then posts an approving + review, which replaces the earlier one), or use [`--passive-reviews`][passive-reviews]. +- Deleting a review's outdated comments needs Gitea v1.25 or newer. Older versions only resolve them. + +```yaml title=".gitea/workflows/cpp-linter.yml" +name: cpp-linter +on: pull_request + +jobs: + cpp-linter: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + # install cpp-linter here, see "Quick start" + - name: Run cpp-linter + env: + GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }} + run: >- + cpp-linter + --style=file + --tidy-checks='' + --thread-comments=update + --no-lgtm=false + --pr-review=true +``` + +See [Quick start][quick-start] for the ways to install cpp-linter. + +## Forgejo + +Forgejo uses the same client as Gitea, so everything in the [Gitea](#gitea) section applies. +In addition: + +- [Forgejo Runner][forgejo-runner] v7.0.0 or newer is needed. Older runners do not set + `FORGEJO_ACTIONS`. +- The runner sets `FORGEJO_TOKEN` for each job, and cpp-linter uses it when `GITEA_TOKEN` is not set. +- A review's outdated comments are neither resolved nor deleted. + +## GitLab + +GitLab v17.9 or newer is needed. + +- Store an access token as a [masked CI/CD variable][gitlab-masked-vars] named `GITLAB_TOKEN`. + The job token (`CI_JOB_TOKEN`) is not used. See [GitLab token permissions][gitlab-permissions] + for the scopes and the role that each feature needs. + Comments and reviews are posted as the token's user, so a project or group access token + (which has its own bot user) is a good fit. +- Run cpp-linter in a [merge request pipeline][gitlab-mr-pipelines]. Only these pipelines have + the `CI_MERGE_REQUEST_IID` variable, which tells cpp-linter that the job belongs to a merge request. + In other pipelines, cpp-linter checks the changes of the pipeline's commit and posts no comments. +- Thread comments are only posted for merge requests, not for commits. +- GitLab has no step summary and no output variables. The values of the output variables are + printed in the job's log, for example `checks-failed: 5`. +- cpp-linter exits with code 0 when checks fail. Because there are no output variables, a job that + should fail on findings has to look for the `checks-failed` line in the log. +- Turn off [`--file-annotations`][file-annotations]. GitLab has no equivalent, and each annotation + would be printed in the job's log instead. + +```yaml title=".gitlab-ci.yml" +cpp-linter: + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + script: + # install cpp-linter here, see "Quick start" + - >- + cpp-linter + --style=file + --tidy-checks='' + --thread-comments=update + --pr-review=true + --file-annotations=false +``` + +The token is not passed in the example because GitLab exposes CI/CD variables to the job as +environment variables. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 2d205019..5af554dc 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -10,6 +10,7 @@ nav: - migration.md - pr-review-caveats.md - permissions.md + - git-servers.md - python.md - node.md - Changes: