Implementing Release Automation

1. Creating Releases

Property	Description	Example
release	Defines a release in GitLab CI/CD	`release:`
tag_name	Name of the tag to create	`tag_name: v1.0.0`
name	Name of the release	`name: Release v1.0.0`
description	Description of the release	`description: Release notes for v1.0.0`
ref	Branch or tag to create the release from	`ref: main`
assets.links	Links to release assets	`assets.links: [{ name: 'artifact', url: 'https://example.com/artifact.zip' }]`

Example: Creating a Release

release_job:
  stage: release
  script:
    - echo "Creating release"
  release:
    tag_name: v1.0.0
    name: Release v1.0.0
    description: Release notes for v1.0.0
    ref: main

Note: The release keyword is available in GitLab CI/CD starting from version 13.0.

2. Setting Release Name and Tag

Property	Description	Example
release.name	Name of the release	`Release v1.2.0`
release.tag_name	Tag name for the release	`v1.2.0`

Example: Setting Release Name and Tag in GitLab CI

release_job:
  stage: release
  script:
    - echo "Creating release"
  release:
    name: "Release $CI_COMMIT_TAG"
    tag_name: "$CI_COMMIT_TAG"

3. Adding Release Description

Property	Description	Values	Notes
release.description	Release description content	`string`	Markdown supported
release.tag_name	Tag name for the release	`string`	Must match existing tag
release.name	Human-readable release name	`string`	Optional, defaults to tag name

Example: Setting Release Description

release:
  tag_name: v1.2.0
  name: Release v1.2.0
  description: |
    This release includes:
    - Bug fixes for login flow
    - Performance improvements in dashboard
    - New API endpoints for user management

Note: Release descriptions support Markdown formatting for rich content display.

4. Creating Release Assets

Asset Type	Description	Configuration	Notes
artifact	Build artifacts to be stored and downloaded	`artifacts:` section in job	Use `paths` to define files/dirs
job	Release job that creates assets	`release:` keyword in job	Must be defined in a job that runs after build
package	Package files (e.g. .deb, .rpm)	`artifacts:` with `package` type	Can be uploaded to GitLab Package Registry

Example: Creating Release Assets

build_job:
  stage: build
  script:
    - echo "Building project..."
    - mkdir -p dist
    - cp -r src/* dist/
  artifacts:
    paths:
      - dist/

release_job:
  stage: release
  script:
    - echo "Creating release assets..."
  release:
    tag_name: v1.0.0
    name: Release v1.0.0
    description: "Release notes for version 1.0.0"
    assets:
      links:
        - name: "Source Code"
          url: "https://gitlab.com/group/project/-/archive/v1.0.0/source.tar.gz"

Note: Artifacts are stored for the duration of the job and can be accessed by downstream jobs in the same pipeline.

Warning: Ensure that sensitive data is not included in artifacts or release assets.

5. Generating Changelog

Option	Values	Description
changelog_file	`CHANGELOG.md`	File path where the changelog will be generated
gitlab_token	`$CI_JOB_TOKEN`	Token used to authenticate with GitLab API
release_tag	`v1.0.0`	Tag name for the release being generated
previous_tag	`v0.9.0`	Previous tag to compare changes from

Example: Using GitLab Changelog Generator

git log --oneline --decorate=short v0.9.0..v1.0.0 | grep -E "^\w+\s*\|\s*.*" | sed 's/^\w\+\s*|\s*//' > CHANGELOG.md

Note: Ensure the git log command includes all relevant commits between tags.

Warning: Manual updates to CHANGELOG.md may conflict with automated generation.

Feature	Status	Notes
Automated Changelog	NEW	Available in GitLab 16.0+
Custom Formatting	DEPRECATED	Removed in GitLab 15.0, replaced with structured format

6. Using Semantic Versioning

Version Format	Pattern	Description
MAJOR.MINOR.PATCH	`1.2.3`	Major version for breaking changes, minor for features, patch for bug fixes

Example: Version Bump in GitLab CI

release:
  stage: release
  script:
    - echo "Current version: $CI_COMMIT_TAG"
    - |
      if [[ "$CI_COMMIT_TAG" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
        MAJOR=$(echo "$CI_COMMIT_TAG" | cut -d. -f1)
        MINOR=$(echo "$CI_COMMIT_TAG" | cut -d. -f2)
        PATCH=$(echo "$CI_COMMIT_TAG" | cut -d. -f3)
        NEW_PATCH=$((PATCH + 1))
        echo "Bumping patch to $MAJOR.$MINOR.$NEW_PATCH"
      fi
  only:
    - tags

Note: GitLab CI does not automatically bump versions; you must implement version increment logic in your scripts.

Version Component	Change Trigger	Example
MAJOR	Breaking change	`1.0.0` → `2.0.0`
MINOR	New feature (non-breaking)	`1.2.0` → `1.3.0`
PATCH	Bug fix (non-breaking)	`1.2.3` → `1.2.4`

Comparison: Manual vs Automated Versioning

Manual: Requires developer to update version files and tag manually
Automated: Uses tools like semantic-release or GitLab's built-in tag parsing to auto-bump versions

7. Automating Version Bumps

Method	Description	Example	Notes
GitLab CI/CD Variables	Use predefined variables to access version information	`VERSION=$CI_COMMIT_TAG`	Available in tagged builds
Semantic Versioning	Automatically increment version numbers based on commit messages	`version: v1.0.0`	Requires `semantic-release` or similar tools
GitLab API	Update project version via GitLab API	`curl --request PUT \ --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \ --form "tag_name=v2.0.0" \ "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/repository/tags"`	Requires appropriate permissions

Example: Using GitLab CI to Bump Version

release:
  stage: release
  script:
    - echo "Current version: $CI_COMMIT_TAG"
    - |
      if [[ "$CI_COMMIT_TAG" == v* ]]; then
        NEW_VERSION=$(echo "$CI_COMMIT_TAG" | sed 's/v//')
        echo "New version: $NEW_VERSION"
      fi
  only:
    - tags

Note: Version bumping should be handled carefully to avoid conflicts in multi-branch environments.

8. Publishing Release Notes

Field	Description	Example
release_notes	Release notes content or file path	`release_notes.md`
tag_name	Tag to create release for	`v1.0.0`
description	Release description (optional)	`Release notes for version 1.0.0`

Example: Publishing Release Notes

release:
  tag_name: "v1.0.0"
  description: "Release notes for version 1.0.0"
  release_notes: "release_notes.md"

Note: Release notes can be sourced from a file or directly specified in the YAML.

9. Using Release Milestones

Milestone	Description	Usage	Status
release.milestone.title	Defines the title of the release milestone	`release.milestone.title = "Release v1.0"`	NEW
release.milestone.description	Provides a description for the milestone	`release.milestone.description = "Final release for version 1.0"`	NEW
release.milestone.due_date	Sets the due date for the milestone	`release.milestone.due_date = "2026-05-30"`	NEW
release.milestone.start_date	Defines the start date for the milestone	`release.milestone.start_date = "2026-04-01"`	NEW

Example: Configure Release Milestone in GitLab CI

release:
  milestone:
    title: "Release v1.0"
    description: "Final release for version 1.0"
    due_date: "2026-05-30"
    start_date: "2026-04-01"

Note: Milestones can be used to organize and track the progress of releases in GitLab.

10. Creating Pre-Release Versions

Option	Values	Notes
release_tag	`pre-release-v1.2.0-rc1`	Tag name for pre-release version
release_name	`Release Candidate 1`	Name displayed in GitLab UI
release_description	`Pre-release version with new features and bug fixes`	Description for release notes

Example: Creating a Pre-Release Version

release:
  tag_name: "pre-release-v1.2.0-rc1"
  name: "Release Candidate 1"
  description: "Pre-release version with new features and bug fixes"
  ref: "feature-branch"

Note: Pre-release versions can be created using GitLab's UI or via API. They are useful for testing and feedback before final release.