Commit c9c55a0e authored by Alexis Deruelle's avatar Alexis Deruelle Committed by Alexis Deruelle
Browse files

fix(docs): auto-release CI_JOB_TOKEN limitation 

When `CI_JOB_TOKEN` is used for authentication and `auto-release-enabled`
is `true`, GitLab does not trigger a new pipeline for the release tag
pushed by semantic-release. This was undocumented, causing users to
silently lose their tag pipelines with no explanation.

- Add a warning note to the `CI_JOB_TOKEN` entry in the
  "Supported authentication methods" README section
- Add a cross-reference warning at the tag pipeline description
- Add a runtime `log_warn` in the template script, gated on
  `SEMREL_AUTO_RELEASE_ENABLED=true`, linking to the GitLab docs

Closes #73
parent fbea176c

README.md

+3 −0
Original line number Diff line number Diff line
@@ -70,6 +70,7 @@ The semantic-release template automatically handles GitLab authentication using 
    - Used automatically when no explicit token is provided

    - Requires enabling [Allow Git push requests to the repository](https://docs.gitlab.com/ci/jobs/ci_job_token/#allow-git-push-requests-to-your-project-repository)

    - Navigate to: `Settings → CI/CD → Job token permissions` in your project

    - :warning: **Limitation**: GitLab [does not trigger new pipelines for commits or tags pushed via `CI_JOB_TOKEN`](https://docs.gitlab.com/ci/jobs/ci_job_token/#the-semantic-release-tool-and-job-tokens). This means that the release tag or commits pushed back by semantic-release (e.g. changelog, version bump) **will not start a new pipeline**. If you need pipelines to be triggered by the release tag, use an explicit `GITLAB_TOKEN` or `GL_TOKEN` instead.



## Jobs
@@ -304,6 +305,8 @@ With this done: 
* the semantic-release will analyse each commit on your production branch, and will possibly create a Git tag if it determined a release has to be performed,

* the Git tag will trigger a tag pipeline during which every to-be-continuous template will take care of publishing its versioned package (using the Git tag as the version) to an appropriate packages repository.



:warning: The tag pipeline is only triggered if an explicit `GITLAB_TOKEN` or `GL_TOKEN` is used for authentication. When using `CI_JOB_TOKEN`, GitLab will not trigger a pipeline for the pushed tag (see [Supported authentication methods](#supported-authentication-methods)).



#### How to override the Git commit comment



In most cases it is recommended to use `chore(release): ${nextRelease.version} [skip ci on prod]` as message template.\

templates/gitlab-ci-semrel.yml

+3 −0
Original line number Diff line number Diff line
@@ -560,6 +560,9 @@ stages: 
        else

          log_info "using \\e[33;1mCI_JOB_TOKEN\\e[0m for authentication"

          log_info "ensure 'allow CI job tokens to push to this repository' is enabled at ${CI_PROJECT_URL}/-/settings/ci_cd#js-token-access"

          if [[ "$SEMREL_AUTO_RELEASE_ENABLED" == "true" ]]; then

            log_warn "CI_JOB_TOKEN does not trigger new pipelines: the release tag or commits pushed by semantic-release will NOT start a new pipeline (see https://docs.gitlab.com/ci/jobs/ci_job_token/#the-semantic-release-tool-and-job-tokens). Use GITLAB_TOKEN or GL_TOKEN if you need pipelines to be triggered by the release tag."

          fi

        fi

  

        commitPresetConfig=$(generate_commit_preset_conf)