GitLab

Provides helpers for resolving merge request context, posting MR comments, fetching avatars, calculating job and pipeline duration, and creating GitLab releases.

Usage

include:
  - project: hosstio/gitlab-pipelines
    file: helpers/gitlab.yaml

Variables

Variable	Default	Description
GITLAB_AUTH_TOKEN	$CI_JOB_TOKEN	Token used for API requests: the default job token works for all jobs; set a Personal Access Token here only if you need broader API access
GITLAB_PROJECT_NAME	$CI_PROJECT_TITLE	Project display name, also the app name in deploy messages
GITLAB_PROJECT_SLUG	$CI_PROJECT_NAME	Project slug
GITLAB_PROJECT_URL	https://gitlab.com/$CI_PROJECT_PATH	Project URL
GITLAB_MESSAGE_URL	https://gitlab.com/api/v4/projects/.../notes	MR notes API endpoint
GITLAB_RELEASE_URL	https://gitlab.com/api/v4/projects/.../releases	Releases API endpoint
GITLAB_MERGE_REQUESTS_URL	$CI_PROJECT_URL/-/merge_requests	MR list URL
GITLAB_MERGE_REQUEST_CREATE_URL	$CI_PROJECT_URL/-/merge_requests/new?...	New MR URL for current branch
GITLAB_CODE_CHANGES_URL	$CI_PROJECT_URL/-/compare/...	Diff URL between before and after SHA
GITLAB_PIPELINE_URL	$CI_PROJECT_URL/-/pipelines/$CI_PIPELINE_ID	Current pipeline URL
GITLAB_PIPELINE_JOB_URL	$CI_PROJECT_URL/-/jobs/$CI_JOB_ID	Current job URL
GITLAB_PIPELINES_URL	$CI_PROJECT_URL/-/pipelines?...	Pipeline list URL for current branch
GITLAB_ROLLBACK_URL	$GITLAB_PIPELINES_URL	Rollback URL (same as pipelines list)

Section helpers (.gitlab_section_helpers)

Requires bash. Uses ${var//pattern/replacement}, printf '%q', and arrays, none of which are available in POSIX sh. Images based on Alpine (e.g. docker:cli) run /bin/sh and will fail if this block is loaded. Use .log_helpers from helpers/default.yaml for those images instead.

Defines shell functions for wrapping job log output in GitLab CI's custom collapsible sections. Sections appear in bold cyan in the job log, matching GitLab's own runner headers, and show elapsed time per section.

Includes all .log_helpers functions. Also enables set -o pipefail in each shell context where it is loaded. GitLab CI runs before_script, script, and after_script in separate shells, so pipefail is set in each one automatically when the helpers are loaded.

Function	Behaviour
section "id" "Title"	Opens a section, expanded by default
section_collapsed "id" "Title"	Opens a section, collapsed by default
section_end "id"	Closes the section
print_command <command>	Prints the fully expanded command before executing it (see below)
print_command_pty <command>	Like print_command but allocates a PTY via unbuffer, for tools that disable color when stdout is not a TTY (e.g. dyff)
log_debug "message"	Prints a dim grey [DEBUG] line to stderr
log_info "message"	Prints a bold blue [INFO] line to stderr
log_warning "message"	Prints an orange [WARNING] line to stderr
log_error "message"	Prints a bold red [ERROR] line to stderr
log_env "pattern"	Prints env vars matching the grep pattern; keys in cyan bold, values in yellow

Titles support shell variable expansion, so runtime context such as release name or namespace can be included directly: section "helm_install" "Helm Install — release \"$HELM_RELEASE\" into namespace \"$HELM_NAMESPACE\"", as helpers/helm.yaml opens its install section.

The functions must be defined before they are called. Wire them in via !reference as the first item of any before_script, script, or after_script that uses them. In jobs that extend .helm, this is done automatically: .helm's before_script already includes this reference.

print_command helper

print_command prints the fully expanded command before executing it:

$ helm diff upgrade my-app ./chart --namespace staging --allow-unreleased ...
<diff output>

Unlike a plain echo, the printed and executed argument list are identical, so no drift is possible. Unlike global set -x, the trace is scoped to the one command so awk blocks, function definitions, and other plumbing stay quiet.

Use it for any command where seeing the exact invocation in the log is valuable:

print_command helm upgrade my-app ./chart --namespace staging --install --wait
print_command kubectl logs -n staging -l app=my-app --tail=100

Examples

deploy:
  before_script:
    - !reference [.gitlab_section_helpers, script]
  script:
    - |
      section "build" "Build: $CI_PROJECT_NAME"
      print_command make build
      section_end "build"
    - |
      section_collapsed "test_output" "Test Output"
      make test
      section_end "test_output"

Job duration (.gitlab_job_duration)

Calculates the elapsed time since CI_JOB_STARTED_AT and exports:

Variable	Description
CI_JOB_STARTED_TIMESTAMP	Unix timestamp of job start
CI_JOB_DURATION_FORMATTED	Human-readable duration, e.g. 2m 34s

Typically called via !reference in after_script before sending notifications.

deploy:
  after_script:
    - !reference [.gitlab_job_duration, script]
    - echo "Job took $CI_JOB_DURATION_FORMATTED"

Pipeline duration (.gitlab_pipeline_duration)

Calculates the elapsed time since CI_PIPELINE_CREATED_AT and exports:

Variable	Description
CI_PIPELINE_CREATED_TIMESTAMP	Unix timestamp of pipeline creation
CI_PIPELINE_DURATION_FORMATTED	Human-readable duration, e.g. 5m 12s

deploy:
  after_script:
    - !reference [.gitlab_pipeline_duration, script]
    - echo "Pipeline has been running for $CI_PIPELINE_DURATION_FORMATTED"

Merge request (.gitlab_merge_request)

Resolves GITLAB_MERGE_REQUEST_IID and GITLAB_MERGE_REQUEST_URL from CI_OPEN_MERGE_REQUESTS in before_script. Falls back to the new MR URL when no open MR is found.

Examples

Typically called via !reference in after_script so the MR URL is available for notifications.

deploy:
  after_script:
    - !reference [.gitlab_merge_request, before_script]
    - echo "MR: $GITLAB_MERGE_REQUEST_URL"

MR comment (.gitlab_message)

Posts a comment on the current merge request as an after_script step.

Variables

Variable	Default	Description
GITLAB_MESSAGE_BODY	Hello world!	Comment body
GITLAB_MESSAGE_DATA	body=$GITLAB_MESSAGE_BODY	POST data sent to the API

Examples

deploy:
  extends: .gitlab_message
  variables:
    GITLAB_MESSAGE_BODY: "Deployed $CI_COMMIT_REF_NAME to production"
  script:
    - helm upgrade ...

Project avatar (.gitlab_project)

Fetches the project avatar URL from the GitLab API and exports it as GITLAB_PROJECT_AVATAR. Falls back to a placeholder image if no avatar is set.

Examples

Typically called via !reference in after_script to include the project avatar in a Slack notification.

deploy:
  after_script:
    - !reference [.gitlab_project, before_script]
    - echo "$GITLAB_PROJECT_AVATAR"

User avatar (.gitlab_user_avatar)

Resolves the current user's avatar URL and exports it as GITLAB_USER_AVATAR. Tries the GitLab account avatar, then the commit author's Gravatar, falling back to an identicon.

Examples

Typically called via !reference in after_script to include the triggering user's avatar in a Slack notification.

deploy:
  after_script:
    - !reference [.gitlab_user_avatar, before_script]
    - echo "$GITLAB_USER_AVATAR"

Release (.gitlab_release)

Creates a GitLab release when a tag is pushed. Skips gracefully if the release already exists. Only runs on tag pipelines.

Variables

Variable	Default	Description
GITLAB_RELEASE_NAME	$CI_COMMIT_TAG	Release title
GITLAB_RELEASE_MESSAGE	$CI_COMMIT_TAG_MESSAGE	Release description
GITLAB_RELEASE_TAG	$CI_COMMIT_TAG	Tag to create the release for

Examples

release:
  extends: .gitlab_release
  stage: publish