GitHub Slug action

This GitHub Action will expose the slug/short values of some GitHub environment variables inside your GitHub workflow.

Overview

SLUG on a variable will

• put the variable content in lower case
• replace any character by - except 0-9, a-z, ., and _
• remove leading - characters
• limit the string size to 63 characters
• remove trailing - characters

Others Slug-ish variables are available

• SLUG_URL on a variable to have a slug variable compliant to be used in a URL
  • Like SLUG but ., and _ are also replaced by -
• SHORT on a variable will limit the string size to ~8 characters
  • Useful for sha value
• <KEY>_PART on a variable will give a part of a variable defined by a key
  • Like GITHUB_REPOSITORY_OWNER_PART for the owner part of GITHUB_REPOSITORY
• <VAR>_CS on other variables to keep the value case-sensitive
  • Like GITHUB_REF_SLUG_CS

Installation

Add this step to your workflow

steps:
  - name: Inject enhanced GitHub environment variables
    uses: rlespinasse/github-slug-action@v5

Caution

Use Dependabot to maintain your github-slug-action version updated in your GitHub workflows.

Configuration Options

Tip

Check for more examples (OS usage, URL use, ...)

With a prefix

steps:
  - name: Inject enhanced GitHub environment variables
    uses: rlespinasse/github-slug-action@v5
    with:
      prefix: CI_

With another max length for slug values

steps:
  - name: Inject enhanced GitHub environment variables
    uses: rlespinasse/github-slug-action@v5
    with:
      slug-maxlength: 80 # Use 'nolimit' to remove use of a max length (Default to 63)

With another length for short values

steps:
  - name: Inject enhanced GitHub environment variables
    uses: rlespinasse/github-slug-action@v5
    with:
      short-length: 7 # By default it's up to Git to decide, use 8 to have the v3.x behaviour

The length of a short sha depends on the size of your repository and can differ over time :

• set 7 to keep the small repository behaviour,
• set 8 to reproduce v3 behaviour,
• set 4 as the minimum length possible.

Warning

If you leave it empty, you need to checkout the source first to let Git decide the size by itself by using git rev-parse behaviour.

The default is the effective value of the core.abbrev configuration variable.

Available Environment variables

Tip

If you don't find what you search for

• Read more about available GitHub variables, and propose a new custom variable.
• Use your own variable with slugify-value, or shortify-git-revision for git reference.

Enhanced variables

• GITHUB_REF_POINT will contain the reference name (branch or tag)
  • based on GITHUB_HEAD_REF in a pull-request* event context,
  • based on GITHUB_REF_NAME in other event context.

Note

All enhanced variables are available in all slug formats.

Partial variables

Variable	Description
GITHUB_REPOSITORY_OWNER_PART	The Owner part of GITHUB_REPOSITORY variable
GITHUB_REPOSITORY_NAME_PART	The Repository name part of GITHUB_REPOSITORY variable

Slug variables

Tip

Available in standard and case-sensitive (_CS) versions.

Variable	Description
GITHUB_REPOSITORY_SLUG	The owner and repository name.
GITHUB_REPOSITORY_OWNER_PART_SLUG	The owner name.
GITHUB_REPOSITORY_NAME_PART_SLUG	The repository name.
GITHUB_REF_SLUG	The branch or tag ref that triggered the workflow.
GITHUB_REF_NAME_SLUG	This value matches the branch or tag name shown on GitHub.
GITHUB_HEAD_REF_SLUG	The branch of the head repository.
GITHUB_BASE_REF_SLUG	The branch of the base repository.
GITHUB_EVENT_REF_SLUG	The Git reference resource associated to triggered webhook.

URL-Safe Slug variables

Same as slug variables but URL-compliant

Tip

Available in standard and case-sensitive (_CS) versions.

Variable	Description
GITHUB_REPOSITORY_SLUG_URL	The owner and repository name.
GITHUB_REPOSITORY_OWNER_PART_SLUG_URL	The owner name.
GITHUB_REPOSITORY_NAME_PART_SLUG_URL	The repository name.
GITHUB_REF_SLUG_URL	The branch or tag ref that triggered the workflow.
GITHUB_REF_NAME_SLUG_URL	This value matches the branch or tag name shown on GitHub.
GITHUB_HEAD_REF_SLUG_URL	The branch of the head repository.
GITHUB_BASE_REF_SLUG_URL	The branch of the base repository.
GITHUB_EVENT_REF_SLUG_URL	The Git reference resource associated to triggered webhook.

Short variables

Variable	Description
GITHUB_SHA_SHORT	The commit SHA that triggered the workflow.
GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT	The commit SHA on pull request that trigger workflow.

Migration from previous versions

v4 to v5

The GITHUB_REF_NAME SLUG/SLUG_URL variables don't work the same way as before

Tip

If you use v5 or related versions, you need to use GITHUB_REF_POINT instead of GITHUB_REF_NAME to get the behaviour of the v4 action.

Before v5, the behaviour was the same as the GitHub one except on pull_request* workflows (Ready the full story).

• ${{ env.GITHUB_REF_NAME }} will serve the behaviour of this action,
• $GITHUB_REF_NAME will serve the behaviour of GitHub Action.

On pull_request* workflows, the content will be <PR-number>/merge instead of the branch name. So you need to use GITHUB_REF_POINT instead

steps:
  - name: Inject enhanced GitHub environment variables
    uses: rlespinasse/github-slug-action@v5
  - run: |
      echo "Branch Name: ${GITHUB_REF_POINT}"
    shell: bash

Then ${{ env.GITHUB_REF_POINT }}, and $GITHUB_REF_POINT will serve the behaviour of this action. And ${{ env.GITHUB_REF_NAME }}, and $GITHUB_REF_NAME will serve the behaviour of GitHub Action.

v3 to v4

Since v4, Git manages the short variables using git rev-parse behaviour. The length of a short sha depends on the size of your repository and can differ over time.

To manage that moving length, you can use the short-length input

• set 7 to reproduce small repository behaviour
• set 8 to reproduce v3 behaviour

Warning

The minimum length is 4, the default is the effective value of the core.abbrev configuration variable.

So to reproduce previous behaviour, use

steps:
  - name: Inject enhanced GitHub environment variables
    uses: rlespinasse/github-slug-action@v5
    with:
      short-length: 8 # Same as v3 and before

Troubleshooting

One of the environment variables doesn't work as intended

Warning

When you set a custom environment variable, you cannot use any of the default environment variable names. For a complete list of these, see Default environment variables. If you attempt to override the value of one of these default environment variables, the assignment is ignored.

If a variable starts to be used as a default environment variable, the environment variable may behave differently than the expected one.

If this append, the ${{ env.GITHUB_AWESOME_VARIABLE }} and $GITHUB_AWESOME_VARIABLE expression will not works in the same way.

• ${{ env.GITHUB_AWESOME_VARIABLE }} will serve the behaviour of this action,
• $GITHUB_AWESOME_VARIABLE will serve the behaviour of GitHub Action.

Otherwise, the two expressions will serve the behaviour of this action. This will not occur if you use the prefix input to avoid the issue.

Important

If detected, the maintainers of this action will choose the best course of action depending on the impact.

An action could not be found at the URI

If your workflow fails on the Set up job task with this kind of log

Download action repository 'rlespinasse/github-slug-action@GIT_REFERENCE'
##[error]An action could not be found at the URI 'https://api.github.com/repos/rlespinasse/github-slug-action/tarball/GIT_REFERENCE'

If the GIT_REFERENCE value is

• v4.x or after, following the end-of-life for a branch security process, this branch can be deleted.
• master, the branch doesn't exist anymore, read more about it on the corresponding issue (EOL issue)

Please, use the current Major tag v5 or a version tag (see releases pages) to fix your workflow.

Thanks for talking about us

In English 🇬🇧

• Action spotlight by Michael Heap
• Serverless Deploy Previews on GitHub Actions
• Let's Build a Continuous Delivery and Branching Process with GitHub Actions, Vercel and Heroku
• Celebrating 5 Years of github-slug-action on sfeir.dev

In French 🇫🇷

• Mettre en place une CI/CD Angular avec GitHub Actions & Netlify
• GitHub Actions : enfin des pipelines accessibles aux développeurs
• GitHub-slug-action : 5 ans d'open source pour cette GitHub Action essentielle au CI/CD

In Chinese 🇨🇳

• 利用github-slug-action暴漏GitHub Action上下文中的关键变量

The next one is you. Don't hesitate to add yourself to one of these lists.