New predefined CI environment variable: CI_COMMIT_BRANCH

Problem to solve

Within a .gitlab-ci.yml file (when crafting only/except conditions, for example), developers may wish to reference / match against the specific branch name to which the commit in question was applied. However, the value of the "CI_COMMIT_REF_NAME" variable is inconsistent: it will only reference the branch name if a tag was not applied. There is already a "CI_COMMIT_TAG" variable (which will be undefined/empty when a tag has not been applied), so a corresponding "CI_COMMIT_BRANCH" variable seems like a reasonable complement.

Intended users

Further details

There are considerably more ambitious modifications to CI rules (#27863 (closed) comes to mind) that may make some use cases OBE should they be successfully merged into a production release. However, the consistency of including "CI_COMMIT_BRANCH" along with other "CI_COMMIT_..." variables seems worthwhile regardless.

Proposal

The branch name can be queried from the repository, once extracted, by simple command line:

git branch --format="%(if)%(HEAD)%(then)%(refname:short)%(end)"

Permissions and Security

Identical to existing "CI_COMMIT_..." predefined CI environmental variable access

Documentation

Most importantly, the new variable should be listed in the "Predefined environment variables reference" documentation at (for example) https://docs.gitlab.com/ee/ci/variables/predefined_variables.html CI documentation pages.

Examples could also be included in (for example) only/except documentation "GitLab CI/CD Pipeline Configuration Reference" at (for example) https://docs.gitlab.com/ee/ci/yaml/README.html CI documentation pages.

Testing

Low risk. Should not impact quality of existing product. Should be robustly compatible.

What does success look like, and how can we measure that?

Successfully implemented, the environment variable "$CI_COMMIT_BRANCH" will be available for utilization/reference in .gitlab-ci.yml files.

What is the type of buyer?

This should be included in the same tier/level as other standard CI features.