GitHub Slug Action
Tags: github, githubactions
Published: 2021-04-26 06:52:58

---
title: GitHub Slug Action
published: true
date: 2021-04-23 18:41:27 UTC
tags: github, githubactions
canonical_url: https://michaelheap.com/github-slug-action/
series: Action Spotlight
---

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.

| Fact Sheet | |
| --- | --- |
| Author | rlespinasse |
| Contributors | 9 |
| Stars | 106 |
| Repo | [https://github.com/rlespinasse/github-slug-action](https://github.com/rlespinasse/github-slug-action) |
| Marketplace | [https://github.com/marketplace/actions/github-slug-action](https://github.com/marketplace/actions/github-slug-action) |

## 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/github-slug-action@v3.x
```

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](https://github.com/rlespinasse/github-slug-action/blob/v3.x/docs/slug-variables.md) docs. If you’re looking for slugs that are safe to use in a URL, you might be interested in the [URL slug variables](https://github.com/rlespinasse/github-slug-action/blob/v3.x/docs/slug-url-variables.md) 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](https://github.com/rlespinasse/github-slug-action/blob/v3.x/src/slug.ts#L106-L108)
- [Removing refs/\* from GITHUB\_REF](https://github.com/rlespinasse/github-slug-action/blob/v3.x/src/slug.ts#L114-L116)
- [Ensure that all slugs are less than 63 characters long](https://github.com/rlespinasse/github-slug-action/blob/v3.x/src/slug.ts#L1)

If you want to see all of the variables it’s creating in the source code, they’re all [available in `main.ts`](https://github.com/rlespinasse/github-slug-action/blob/v3.x/src/main.ts#L107-L170).

The action itself is compiled and [pushed to the repo](https://github.com/rlespinasse/github-slug-action/tree/v3.x/dist) so that people can use it directly. This isn't a pattern I like personally (I prefer to use the [build and tag action](http://localhost:8080/build-and-tag-action/)) but it means that consumers can use the javascript runtime so it's a reasonable trade off.