GitHub Slug Action

We're looking at a different kind of action today! This action doesn't actually do anything. Instead, it makes more information available in your workflow and the environment for other actions to use.

What does it do?

The github-slug-ref action provides information that’s commonly needed in workflows in a useful format. By default, variables such as GITHUB_REF are in the format refs/heads/main or refs/tags/v1.0.0. This catches people out as they’re not used to thinking about if what they’re referencing is a branch or a tag, and they’re definitely not used to the refs prefix.

Once the rlespinasse/github-slug-action action has been included in your workflow, some new environment variables will be available. To include it, add a uses entry within your steps key:

yaml
name: Slug Demo
on: push
jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - uses: rlespinasse/[email protected]

If we think about GITHUB_REF from above, GITHUB_REF_SLUG is available after including this action. If GITHUB_REF was refs/heads/main, GITHUB_REF_SLUG will be main. If the input was refs/tags/v1.0.0, GITHUB_REF_SLUG will be v1.0.0. If you’d like to see a full list of transformations, see the slug variables docs. If you’re looking for slugs that are safe to use in a URL, you might be interested in the URL slug variables too.

Another feature of the action is short variables. In addition to the full sha (available in GITHUB_SHA), this action will make an 8 character prefix available in GITHUB_SHA_SHORT. This can be useful is you need a semi-unique identifier and want a shorter key than the full sha.

In addition to manipulating the existing environment variables, the action also makes some of the information from github.event available as an environment variable. For example, github.event.pull_request.head.sha is available as GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT. This is useful when you’re writing bash scripts and can’t parse event.json.

How does it work?

Looking at the source code, this action is a large collection of regular expressions. It handles cases such as:

• Replacing any non-alphanumeric character
• Removing refs/* from GITHUB_REF
• Ensure that all slugs are less than 63 characters long

If you want to see all of the variables it’s creating in the source code, they’re all available in main.ts.

The action itself is compiled and pushed to the repo so that people can use it directly. This isn't a pattern I like personally (I prefer to use the build and tag action) but it means that consumers can use the javascript runtime so it's a reasonable trade off.