Using the Docker image

The official FerrFlow Docker image ships the binary and can be used directly as a GitLab CI job image.

release:
  image:
    name: ghcr.io/ferrlabs/ferrflow:latest
    entrypoint: [""]
  stage: release
  script:
    - ferrflow release
  variables:
    GITLAB_TOKEN: $CI_JOB_TOKEN
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: on_success

The image's entrypoint is ferrflow, so docker run ghcr.io/ferrlabs/ferrflow:latest check works as is. GitLab runs a job's script through a shell instead, which is why every example here resets it with entrypoint: [""]. Without that line the job fails with unrecognized subcommand 'sh'.

The image ships git, trusts the checkout whatever user cloned it, and signs release commits as FerrFlow <bot@ferrflow.com>. To sign them as the person who triggered the pipeline instead, set GIT_AUTHOR_NAME: $GITLAB_USER_NAME and GIT_AUTHOR_EMAIL: $GITLAB_USER_EMAIL in the job variables.

Full history

release:
  image:
    name: ghcr.io/ferrlabs/ferrflow:latest
    entrypoint: [""]
  variables:
    GIT_DEPTH: 0 # full history: required for tag scanning
    GITLAB_TOKEN: $CI_JOB_TOKEN
  script:
    - ferrflow release
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Using a deploy token

If CI_JOB_TOKEN doesn't have permission to push tags, create a project deploy token with write_repository access and store it as a CI variable:

release:
  image:
    name: ghcr.io/ferrlabs/ferrflow:latest
    entrypoint: [""]
  variables:
    GIT_DEPTH: 0
    GITLAB_TOKEN: $FERRFLOW_DEPLOY_TOKEN # CI variable with write_repository access
  script:
    - ferrflow release
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

MR preview comments

FerrFlow can post a comment on every merge request showing what versions will be bumped when the MR is merged. The comment is automatically updated on each push.

ferrflow-preview:
  image:
    name: ghcr.io/ferrlabs/ferrflow:latest
    entrypoint: [""]
  stage: test
  variables:
    GIT_DEPTH: 0
    GITLAB_TOKEN: $CI_JOB_TOKEN
  script:
    - ferrflow check --comment
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

The comment looks like:

FerrFlow Release Preview

Package	Current	Next	Bump
api	1.5.0	1.6.0	minor

Based on 2 commit(s).

If no releasable changes are detected, the comment says so.

If you store that token as a protected variable, GitLab only exposes it to pipelines on protected branches and tags, and a merge request pipeline from an ordinary branch runs without it. FerrFlow then prints Warning: preview comment not posted: no Gitlab token found in FERRFLOW_TOKEN or GITLAB_TOKEN and the job still succeeds. Either unprotect the variable or use CI_JOB_TOKEN, which every job receives.

GitLab Releases

When GITLAB_TOKEN is set, FerrFlow creates a GitLab Release with the generated changelog as release notes, matching the behaviour of the GitHub integration.