github-slug-action/README.md

GitHub Slug action

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

Table of Contents

• GitHub Slug action
  • Table of Contents
  • Overview
  • Use this action
  • Available Environment variables
    • Enhanced variables
    • Partial variables
    • Slug variables
    • Slug URL variables
    • Short variables
  • Contribute
  • Troubleshooting
    • One of the environment variables doesn't work as intended
    • An action could not be found at the URI
  • Thanks for talking about us

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 and trailing - character
• limit the string size to 63 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 . is 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@v3.x

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

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

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

Contribute

Follow Developers guide

Troubleshooting

One of the environment variables doesn't work as intended

Note: GitHub reserves the GITHUB_ environment variable prefix for internal use by GitHub. Setting an environment variable or secret with the GITHUB_ prefix will result in an error.

Currently, a GitHub workflow setting a GITHUB_ variable will not cause an error, it will just fail silently. And if a custom GITHUB_ variable is in conflict with an official GITHUB_ variable, the offical GITHUB_ variable will override custom one.

Test workflow

name: Test
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: echo ${GITHUB_REF}
      # print "refs/heads/v3.x"
      - run: echo "GITHUB_REF=one_value" >> "$GITHUB_ENV"
      - run: echo ${GITHUB_REF}
      # print "refs/heads/v3.x"
      - run: echo "GITHUB_REF_SLUG=another_value" >> "$GITHUB_ENV"
      - run: echo ${GITHUB_REF_SLUG}
      # print "another_value"

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@master'
##[error]An action could not be found at the URI 'https://api.github.com/repos/rlespinasse/github-slug-action/tarball/master'

The master branch doesn't exists anymore.

The master branch EOL has been set to 2020-10-25 after a 6-month deprecation period (more information on the EOL issue)

Please, use the current branch v3.x or a version tag (see releases pages) in order to fix your workflow.

Thanks for talking about us

• Mettre en place une CI/CD Angular avec GitHub Actions & Netlify (in french 🇫🇷)
• Github Actions : enfin des pipelines accessibles aux développeurs (in french 🇫🇷)
• The next one is you. Don't hesitate to add youself to this list.