Awesome
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
-
except0-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 aslug
variable compliant to be used in a URL- Like
SLUG
but.
, and_
are also replaced by-
- Like
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 ofGITHUB_REPOSITORY
- Like
<VAR>_CS
on others variables to keep the value case-sensitive- Like
GITHUB_REF_SLUG_CS
- Like
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 of the size of your repository and can differ over time :
- set
7
to keep thesmall repository
behaviour, - set
8
to reproducev3
behaviour, - set
4
as the minimum length possible.
[!WARNING] If you leave it empty, you need to checkout the source first in order 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 contains the reference name (branch or tag)- based on
GITHUB_HEAD_REF
in apull-request*
event context, - based on
GITHUB_REF_NAME
in others event context.
- based on
[!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 doesn't work the same way as before
[!TIP] If you use
v5
or related versions, you need to useGITHUB_REF_POINT
instead ofGITHUB_REF_NAME
to get the behaviour of thev4
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
, it's Git who manage the short variables by using git rev-parse
behaviour.
The length of a short sha depends of the size of your repository and can differ over time.
To manage that moving length, you can use short-length
input
- set
7
to reproducesmall repository
behaviour - set
8
to reproducev3
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 start to be used as default environment variable, the environment variable may have a different behaviour 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 expression will serve the behaviour of this action.
This will not occurs 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 of the impact.
An action could not be found at the URI
If your workflow fail 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, the branch don't exists anymore following the end-of-life for a branch security process.master
, the branch don't exists 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) in order to fix your workflow.
Thanks for talking about us
In English :gb:
- 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
In French :fr:
- 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 :cn:
The next one is you. Don't hesitate to add youself to one of these lists.