Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 36 ยท Projects and Practice

Project: Release Automation

Build an automated release flow in GitLab: conventional commits decide the version, a tag pipeline publishes packages and images, and a release page appears with notes and links.

Releasing by hand is a ritual of small steps: pick a number, edit a version file, write notes, build, upload, announce. Every step is a chance to forget something. In this project you design a release flow where the only human decisions are "merge this" and "release now", and everything else follows from commit messages and a tag.

The product is a command-line tool called shelf-cli (any library or tool would do). GitLab cannot run on this site, so the pipeline and settings are read-only; the version logic and the rules evaluation run as JavaScript stand-ins. You will connect ideas from the earlier lessons: Releases and Semantic Versioning, Package Registry, Container Registry and Roles, Permissions and Protected Branches.

The flow

flowchart LR
  MR["merge request with a conventional title"] --> SQ["squash merge to main"]
  SQ --> N["release-notes job: compute next version and notes"]
  N --> H{"maintainer presses play"}
  H --> T["tag vX.Y.Z is created"]
  T --> B["build binaries"]
  B --> PK["upload to Package Registry"]
  B --> IM["push image tags"]
  PK --> RL["create_release job"]
  IM --> RL

Two human decisions (merge and release); everything else is automatic.

Design decisions:

  1. Merge request titles are the commit messages (squash merge), checked by a lint job. The titles use feat, fix and ! for breaking changes.
  2. A preview job on main computes the next version and the notes, and prints them. A maintainer reads them and presses a manual release job.
  3. The release job pushes the tag using a project access token stored as a protected variable (the job token cannot create pipelines from its own tag push in all setups, so a token with write_repository is common; check your version's behavior). Only Maintainers may create v* tags, by protected tag rules.
  4. The tag pipeline builds, publishes and finally creates the release.

The pipeline

YAML
stages: [verify, prepare, build, publish, release]

lint_mr_title:
  stage: verify
  image: alpine:3.20
  script:
    - |
      echo "$CI_MERGE_REQUEST_TITLE" | grep -Eq '^(feat|fix|docs|refactor|test|chore|ci)(\([a-z0-9-]+\))?!?: .{5,}$' \
        || { echo "Title must look like: feat(scope): summary"; exit 1; }
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

next_version:
  stage: prepare
  image: node:22
  script:
    - node ci/next-version.js > version.env
    - cat version.env
  artifacts:
    reports:
      dotenv: version.env
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

tag_release:
  stage: release
  image: alpine/git:latest
  needs: [next_version]
  script:
    - test -n "$NEXT_VERSION" || { echo "Nothing to release"; exit 0; }
    - git tag -a "v$NEXT_VERSION" -m "Release $NEXT_VERSION"
    - git push "https://release-bot:${RELEASE_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" "v$NEXT_VERSION"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual

build_binaries:
  stage: build
  image: golang:1.24
  script:
    - GOOS=linux GOARCH=amd64 go build -o shelf-linux-amd64 ./cmd/shelf
    - GOOS=darwin GOARCH=arm64 go build -o shelf-darwin-arm64 ./cmd/shelf
  artifacts:
    paths: [shelf-linux-amd64, shelf-darwin-arm64]
    expire_in: 1 day
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/

publish_packages:
  stage: publish
  image: curlimages/curl:latest
  needs: [build_binaries]
  script:
    - |
      for f in shelf-linux-amd64 shelf-darwin-arm64; do
        curl --fail --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file "$f" \
          "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/shelf/${CI_COMMIT_TAG}/$f"
      done
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/

create_release:
  stage: release
  image: registry.gitlab.com/gitlab-org/cli:latest
  needs: [publish_packages]
  script: echo "Releasing $CI_COMMIT_TAG"
  release:
    tag_name: $CI_COMMIT_TAG
    name: "shelf $CI_COMMIT_TAG"
    description: "See CHANGELOG.md for the notes of this version."
    assets:
      links:
        - name: "Linux (amd64)"
          url: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/shelf/${CI_COMMIT_TAG}/shelf-linux-amd64"
          link_type: package
        - name: "macOS (arm64)"
          url: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/shelf/${CI_COMMIT_TAG}/shelf-darwin-arm64"
          link_type: package
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/

Things to review in your own design:

  • Rules are evaluated when the pipeline is created, so they cannot read values computed by a job; that is why tag_release checks $NEXT_VERSION inside its script instead of in rules.
  • next_version uses a dotenv report so later jobs get NEXT_VERSION as a variable. The script ci/next-version.js is yours; the example below is a working model of it.
  • The release token must be protected, scoped and rotated; it can create tags, so treat it like a deploy key (see CI Variables and Secrets Security).
  • rules on tag jobs use one regular expression everywhere, so a stray tag like v1.0 or test-123 cannot start a release. A shared variable such as RELEASE_TAG_PATTERN would avoid repeating it.
  • Binary builds use Go as an example; any language works the same way.
  • The tag push from tag_release is a new pipeline (the tag pipeline), distinct from the main pipeline that ran the manual job.
  • A failed create_release job can be re-run safely when the assets exist; make the earlier jobs idempotent as well.

Stand-in: computing the next version

This is what ci/next-version.js might do: read the commit subjects since the last tag, decide the bump and print the dotenv lines and the notes. The input is fixed sample data so the output is repeatable.

JS next-version.js (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: which jobs run for which event?

Release pipelines go wrong when rules let a job run in the wrong place. This evaluator supports the small subset of rule conditions used above and prints which jobs start for different events, so you can check your design before pushing.

JS Rules evaluator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Your turn

  1. Add a rule that creates pre-releases for tags like v2.0.0-rc.1 without moving the :latest-like tags.
  2. Add a job that pushes :1.9.0, :1.9 and :1 image tags (see Container Registry).
  3. Add a rollback story: how do you publish 1.9.1 that reverts the change, and who may do it?
  4. Write the project settings checklist: protected tag v*, the release token as a protected variable with an expiry, the squash setting, and a CODEOWNERS entry for ci/.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why is the release job manual?

    Teams often merge several changes before shipping. A manual step keeps the decision with a person while everything else is automatic.
  2. 2. How do later jobs learn the computed version?

    artifacts:reports:dotenv turns the lines of the file into variables for jobs that need that job.
  3. 3. Why does create_release use needs: [publish_packages]?

    A release page with dead links is worse than none, so it is created after publishing.
  4. 4. What does the regular expression on the tag rules prevent?

    Only strict vX.Y.Z tags match, and protected tags limit who can create them.
  5. 5. A commit says fix(export)!: rename --out to --output. What version bump follows from 1.8.2?

    The exclamation mark means a breaking change, so the major version increases and the others reset.

Summary

  • Make commit messages data: conventional titles with squash merge give you automatic version and notes.
  • Keep two human steps (merge, release) and automate tag, build, publish and release page.
  • Use strict tag patterns, protected tags and a protected, rotated token for tag creation.
  • Order jobs so release links always point to existing files, and test your rules before shipping.

Next: Project: Reviewing a Deployment Design