Skip to content

Latest commit

 

History

History
278 lines (197 loc) · 16.6 KB

README.md

File metadata and controls

278 lines (197 loc) · 16.6 KB
Raw

GitHub Slug action

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

Table of Contents

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 commands are available

  • SLUG_URL on a variable to have a slug variable compliant to be used in an 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 others variables to keep the value case-sensitive
    • Like GITHUB_REF_SLUG_CS

Additional enhanced environment variables can be compute to help you around GitHub environment variables.

Use this action

Add this in your workflow

- name: Inject slug/short variables
  uses: rlespinasse/github-slug-action@v4
Others configurations

  • With a prefix

    - name: Inject slug/short variables
  uses: rlespinasse/github-slug-action@v4
  with:
    prefix: CI_

  • With another max length for slug values

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

  • With another length for short values

    - name: Inject slug/short variables
  uses: rlespinasse/github-slug-action@v4
  with:
    short-length: 7 # By default it's up to git to decide, use 8 to have the v3.x behavior

    Warning: If you leave it empty, you need to checkout the source first in order to let git decide the size by itself.

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

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

Migration from previous versions

The short sha length is not the same as previous version.

  • v4 let git configuration decide of it (but you can override it),
  • v3 and before, it's always a length of 8 characters.

So to reproduce previous behavior, use

- name: Inject slug/short variables
  uses: rlespinasse/github-slug-action@v4
  with:
    short-length: 8 # Same as v3 and before

Available Environment variables

Note: If you don't find what you search for, read more about available GitHub variables, and propose a new custom variable.

Enhanced variables

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

NOTE: All enhanced variables are available in all slug formats.

Partial variables

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

Slug variables

NOTE: _CS suffix available

Variable Slug version of Description
GITHUB_REPOSITORY_SLUG GITHUB_REPOSITORY The owner and repository name.
GITHUB_REPOSITORY
_OWNER_PART_SLUG		 GITHUB_REPOSITORY_OWNER_PART The owner name.
GITHUB_REPOSITORY
_NAME_PART_SLUG		 GITHUB_REPOSITORY_NAME_PART The repository name.
GITHUB_REF_SLUG GITHUB_REF The branch or tag ref that triggered the workflow.
GITHUB_HEAD_REF_SLUG GITHUB_HEAD_REF The branch of the head repository.
Only set for [pull-request][event-pull-request] event and forked repositories.
GITHUB_BASE_REF_SLUG GITHUB_BASE_REF The branch of the base repository.
Only set for [pull-request][event-pull-request] event and forked repositories.
GITHUB_EVENT_REF_SLUG github.event.ref
Only set for following webhook events
  • create
  • delete

Slug URL variables

NOTE: _CS suffix available

Variable Slug URL version of Description
GITHUB_REPOSITORY_SLUG_URL GITHUB_REPOSITORY The owner and repository name.
GITHUB_REPOSITORY
_OWNER_PART_SLUG_URL		 GITHUB_REPOSITORY_OWNER_PART The owner name.
GITHUB_REPOSITORY
_NAME_PART_SLUG_URL		 GITHUB_REPOSITORY_NAME_PART The repository name.
GITHUB_REF_SLUG_URL GITHUB_REF The branch or tag ref that triggered the workflow.
GITHUB_HEAD_REF_SLUG_URL GITHUB_HEAD_REF The branch of the head repository.
Only set for pull-request event and forked repositories.
GITHUB_BASE_REF_SLUG_URL GITHUB_BASE_REF The branch of the base repository.
Only set for pull-request event and forked repositories.
GITHUB_EVENT_REF_SLUG_URL github.event.ref
Only set for following webhook events
  • create
  • delete

Short variables

Variable Short version of Description
GITHUB_SHA_SHORT GITHUB_SHA The commit SHA that triggered the workflow.
GITHUB_EVENT
_PULL_REQUEST
_HEAD_SHA_SHORT		 github.event
.pull_request
.head.sha		 The commit SHA on pull request that trigger workflow.
Only set for following webhook events
  • pull_request
  • pull_request_review
  • pull_request_review_comment
  • pull_request_target

Troubleshooting

The SHORT variables doesn't have the same lengths as before

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 our repository and can differ over time.

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

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

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

One of the environment variables doesn't work as intended

Note: 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 behavior 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 behavior of this action,
  • $GITHUB_AWESOME_VARIABLE will serve the behavior of GitHub Action.

Otherwise the two expression will serve the behavior of this action. This will not occurs if you use the prefix input to avoid the issue.

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

Known environment variable conflicts

GITHUB_REF_NAME

The behavior is the same as the GitHub one except on pull_request* workflows (Ready the full story).

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

On pull_request* workflows, the content will be <PR-number>/merge instead of the branch name.

A possible workaround is to use prefix input

- name: Inject slug/short variables
  uses: rlespinasse/github-slug-action@v4
  with:
    prefix: CI_

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

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 v4 or a version tag (see releases pages) in order to fix your workflow.

Thanks for talking about us

In English 🇬🇧

In French 🇫🇷

In Chinese 🇨🇳

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