Git

Provides pipeline rules and before_script helpers for building commit lists, change summaries, and release notes, and for checking out other repositories.

Usage

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

Variables

Variable	Default	Description
GIT_SHA	$CI_COMMIT_SHA	Full commit SHA
GIT_SHA_SHORT	$CI_COMMIT_SHORT_SHA	Short commit SHA
GIT_COMMITS_BASE_BRANCH	$CI_DEFAULT_BRANCH	Base branch for commit range on new branches
GIT_COMMITS_FORMAT	$GIT_COMMITS_FORMAT_AUTHORS_MARKDOWN	Active format for GIT_COMMITS
GIT_COMMITS_FORMAT_MARKDOWN	- %s (*<url|%h>*)	Markdown commit list format
GIT_COMMITS_FORMAT_TEXT	• %s (%h)	Plain text commit list format
GIT_COMMITS_FORMAT_AUTHORS_MARKDOWN	- %s (*<url|%h>*) - %an	Markdown format with author names
GIT_COMMITS_FORMAT_AUTHORS_TEXT	• %s (%h) - %an	Plain text format with author names
GIT_REPOSITORIES	""	Git URLs, separated by spaces, that .git_repositories checks out
GIT_REPOSITORIES_DIR	/repositories	Where .git_repositories checks them out

Commit list (.git_commits)

Sets GIT_COMMITS_FROM, GIT_COMMITS_TO, and GIT_COMMITS in before_script. Uses CI_COMMIT_BEFORE_SHA when available; otherwise finds the merge base with GIT_COMMITS_BASE_BRANCH.

Examples

These jobs are typically called via !reference rather than extends, because they need to run in both before_script and after_script (which runs in a fresh shell).

deploy:
  before_script:
    - !reference [.git_commits, before_script]
  after_script:
    - !reference [.git_commits, before_script]  # re-run: after_script is a new shell
    - echo "$GIT_COMMITS"

Changes summary (.git_changes_summary)

Sets GIT_CHANGES_SUMMARY in before_script. Uses the tag message, release description, commit description, or MR title, whichever is available first. Truncated to 100 characters.

Examples

deploy:
  after_script:
    - !reference [.git_changes_summary, before_script]
    - echo "$GIT_CHANGES_SUMMARY"

Release notes (.git_release_notes)

Sets GIT_RELEASE_NOTES, GIT_RELEASE_NOTES_LINK_URL, and GIT_RELEASE_NOTES_LINK_TEXT in before_script. Falls back from tag/release message to the relevant CHANGELOG.md section. The CHANGELOG fallback requires .git_commits to also be in the before_script chain. Truncated to 2900 characters.

Examples

deploy:
  after_script:
    - !reference [.git_commits, before_script]
    - !reference [.git_release_notes, before_script]
    - echo "$GIT_RELEASE_NOTES"

Gitflow rules (.gitflow)

Restricts a job to merge request pipelines, git tags, and the default branch. All other branches are skipped.

Examples

test:
  extends: .gitflow
  script:
    - npm test

build:
  extends: .gitflow
  script:
    - docker build .

Repositories (.git_repositories)

Clones each git URL in GIT_REPOSITORIES to $GIT_REPOSITORIES_DIR/<group>/<project> in before_script, with a depth of 1. Repositories on the same GitLab instance clone with the job token, so each of their projects must add the job's project to its job token allowlist (Settings, CI/CD, Job token permissions).

Examples

docs:
  extends: .git_repositories
  variables:
    GIT_REPOSITORIES: "https://gitlab.com/<group>/docs.git"
  script:
    - ls /repositories/<group>/docs