rlespinasse/github-slug-action
1
0
Fork 0
mirror of https://github.com/rlespinasse/github-slug-action.git synced 2026-05-17 10:25:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Reorganize documentation with new reference and explanation sections (#176)

Browse Source 
Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Romain Lespinasse
2026-03-12 14:02:09 +01:00
committed by GitHub
parent 9e7def6155
commit ef035f61a9
23 changed files with 934 additions and 602 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.codespellrc Normal file
View File

@@ -0,0 +1,2 @@
[codespell]
ignore-words-list = ans

264
README.md
View File

@@ -1,34 +1,12 @@
# GitHub Slug action
# GitHub Slug Action
This GitHub Action will expose the slug/short values of [some GitHub environment variables][default-environment-variables] inside your GitHub workflow.
This GitHub Action exposes slug and short values of [GitHub environment variables][default-environment-variables] inside your workflow.
## 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 variables are available
- `SLUG_URL` on a variable to have a `slug` variable compliant to be used in a URL
- Like `SLUG` but `.`, and `_` are also replaced by `-`
- `SHORT` on a variable will limit the string size to [~8 characters](#with-another-length-for-short-values)
- 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 other variables to keep the value case-sensitive
- Like `GITHUB_REF_SLUG_CS`
## Installation
Add this step to your workflow
## Quick Start
```yaml
steps:
- uses: actions/checkout@v6
- name: Inject enhanced GitHub environment variables
uses: rlespinasse/github-slug-action@v5
```
@@ -36,205 +14,80 @@ steps:
> [!CAUTION]
> Use [Dependabot][dependabot] to maintain your `github-slug-action` version updated in your GitHub workflows.
## Configuration Options
## What It Does
- **SLUG** -- Lowercase, replace special characters with `-`, limit to 63 characters. _Dots and underscores preserved._
- **SLUG_URL** -- Same as SLUG, but dots and underscores are also replaced. _Safe for URLs and subdomains._
- **SHORT** -- Shorten Git SHA values to a unique prefix.
- **PART** -- Extract portions of a variable (e.g., owner or repository name from `GITHUB_REPOSITORY`).
- **_CS** -- Case-sensitive variants of SLUG and SLUG_URL (original casing preserved).
> [!TIP]
> Check for more [examples][examples] (OS usage, URL use, ...)
> Read the [slug transformation rules](docs/explanation/slug-transformation-rules.md) for the full algorithm and rationale.
### With a prefix
## Inputs
```yaml
steps:
- name: Inject enhanced GitHub environment variables
uses: rlespinasse/github-slug-action@v5
with:
prefix: CI_
```
| Input | Default | Description |
| ----- | ------- | ----------- |
| `prefix` | `""` | Value prepended to each generated variable name |
| `slug-maxlength` | `63` | Max length of slugified values (`"nolimit"` to disable) |
| `short-length` | _(Git default)_ | Length of short SHA values (minimum `4`) |
### With another max length for slug values
See the [inputs reference](docs/reference/inputs.md) for details.
```yaml
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)
```
## Available Variables
### With another length for short values
| Variable | Type | Description |
| -------- | ---- | ----------- |
| [GITHUB_REF_POINT](docs/reference/variables.md#github_ref_point) | Enhanced | Branch or tag name (consistent across event types) |
| [GITHUB_REPOSITORY_OWNER_PART](docs/reference/variables.md#github_repository_owner_part) | Partial | Owner extracted from repository |
| [GITHUB_REPOSITORY_NAME_PART](docs/reference/variables.md#github_repository_name_part) | Partial | Repository name extracted from repository |
| [GITHUB_REPOSITORY_SLUG](docs/reference/variables.md#github_repository_slug) | Slug | The owner and repository name |
| [GITHUB_REF_SLUG](docs/reference/variables.md#github_ref_slug) | Slug | The branch or tag ref |
| [GITHUB_REF_NAME_SLUG](docs/reference/variables.md#github_ref_name_slug) | Slug | The branch or tag name shown on GitHub |
| [GITHUB_HEAD_REF_SLUG](docs/reference/variables.md#github_head_ref_slug) | Slug | PR head branch |
| [GITHUB_BASE_REF_SLUG](docs/reference/variables.md#github_base_ref_slug) | Slug | PR base branch |
| [GITHUB_EVENT_REF_SLUG](docs/reference/variables.md#github_event_ref_slug) | Slug | Webhook Git ref |
| [GITHUB_SHA_SHORT](docs/reference/variables.md#github_sha_short) | Short | Shortened commit SHA |
| [GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT](docs/reference/variables.md#github_event_pull_request_head_sha_short) | Short | Shortened PR head commit SHA |
```yaml
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 on the size of **your repository** and can differ over time :
- set `7` to keep the `small repository` behaviour,
- set `8` to reproduce `v3` behaviour,
- set `4` as the minimum length possible.
> [!WARNING]
> If you leave it empty, you need to checkout the source first to let Git decide the size by itself by using [`git rev-parse`][git-revparse] behaviour.
>
> The default is the effective value of the [core.abbrev][git-core-abbrev] configuration variable.
## Available Environment variables
All slug variables also have `_SLUG_URL` and `_CS` variants. See the [full variable reference](docs/reference/variables.md).
> [!TIP]
> If you don't find what you search for
>
> - Read more about [available `GitHub` variables](docs/github-variables.md), and propose a [new custom variable][custom-variable].
> - Use your own variable with [slugify-value][slugify-value], or [shortify-git-revision][shortify-git-revision] for git reference.
> If you don't find what you need, read about [available GitHub variables](docs/reference/github-variables.md), [propose a new variable][custom-variable], or use [slugify-value][slugify-value] / [shortify-git-revision][shortify-git-revision] directly.
### Enhanced variables
## Documentation
- `GITHUB_REF_POINT` will contain the reference name (branch or tag)
- based on `GITHUB_HEAD_REF` in a [`pull-request*`][webhooks-and-events] event context,
- based on `GITHUB_REF_NAME` in other event context.
### Tutorial
> [!NOTE]
> All enhanced variables are available in all **slug** formats.
- [Getting started](docs/getting-started.md) -- Step-by-step guide for first-time users
### Partial variables
### How-To Guides
| Variable | Description |
| -------- | ----------- |
| [GITHUB_REPOSITORY_OWNER_PART](docs/partial-variables.md#github_repository_owner_part) | The Owner part of GITHUB_REPOSITORY variable |
| [GITHUB_REPOSITORY_NAME_PART](docs/partial-variables.md#github_repository_name_part) | The Repository name part of GITHUB_REPOSITORY variable |
- [Use a prefix](docs/how-to/use-prefix.md)
- [Configure slug max length](docs/how-to/configure-slug-maxlength.md)
- [Configure short SHA length](docs/how-to/configure-short-length.md)
- [Use slug variables in URLs](docs/how-to/use-slugs-in-urls.md)
- More [workflow examples](https://github.com/rlespinasse/github-slug-action/tree/v5.x/examples) (OS-specific usage, URL patterns)
### Slug variables
### Reference
> [!TIP]
> Available in standard and case-sensitive (`_CS`) versions.
- [Variable reference](docs/reference/variables.md) -- All variables with transformation examples
- [Inputs reference](docs/reference/inputs.md) -- Action inputs specification
- [GitHub variables by event](docs/reference/github-variables.md) -- Which variables are available per event type
| Variable | Description |
| -------- | ----------- |
| [GITHUB_REPOSITORY_SLUG](docs/slug-variables.md#github_repository_slug) | The owner and repository name. |
| [GITHUB_REPOSITORY_OWNER_PART_SLUG](docs/slug-variables.md#github_repository_owner_part_slug) | The owner name. |
| [GITHUB_REPOSITORY_NAME_PART_SLUG](docs/slug-variables.md#github_repository_name_part_slug) | The repository name. |
| [GITHUB_REF_SLUG](docs/slug-variables.md#github_ref_slug) | The branch or tag ref that triggered the workflow. |
| [GITHUB_REF_NAME_SLUG](docs/slug-variables.md#github_ref_name_slug) | This value matches the branch or tag name shown on GitHub. |
| [GITHUB_HEAD_REF_SLUG](docs/slug-variables.md#github_head_ref_slug) | The branch of the head repository. |
| [GITHUB_BASE_REF_SLUG](docs/slug-variables.md#github_base_ref_slug) | The branch of the base repository. |
| [GITHUB_EVENT_REF_SLUG](docs/slug-variables.md#github_event_ref_slug) | The Git reference resource associated to triggered webhook. |
### Explanation
### URL-Safe Slug variables
- [Slug transformation rules](docs/explanation/slug-transformation-rules.md) -- How and why transformations work
Same as slug variables but URL-compliant
## Migration
> [!TIP]
> Available in standard and case-sensitive (`_CS`) versions.
| Variable | Description |
| -------- | ----------- |
| [GITHUB_REPOSITORY_SLUG_URL](docs/slug-url-variables.md#github_repository_slug_url) | The owner and repository name. |
| [GITHUB_REPOSITORY_OWNER_PART_SLUG_URL](docs/slug-variables.md#github_repository_owner_part_slug_url) | The owner name. |
| [GITHUB_REPOSITORY_NAME_PART_SLUG_URL](docs/slug-variables.md#github_repository_name_part_slug_url) | The repository name. |
| [GITHUB_REF_SLUG_URL](docs/slug-url-variables.md#github_ref_slug_url) | The branch or tag ref that triggered the workflow. |
| [GITHUB_REF_NAME_SLUG_URL](docs/slug-url-variables.md#github_ref_slug_url) | This value matches the branch or tag name shown on GitHub. |
| [GITHUB_HEAD_REF_SLUG_URL](docs/slug-url-variables.md#github_head_ref_slug_url) | The branch of the head repository. |
| [GITHUB_BASE_REF_SLUG_URL](docs/slug-url-variables.md#github_base_ref_slug_url) | The branch of the base repository. |
| [GITHUB_EVENT_REF_SLUG_URL](docs/slug-url-variables.md#github_event_ref_slug_url) | The Git reference resource associated to triggered webhook. |
### Short variables
| Variable | Description |
| -------- | ----------- |
| [GITHUB_SHA_SHORT](docs/short-variables.md#github_sha_short) | The commit SHA that triggered the workflow. |
| [GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT](docs/short-variables.md#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 don't work the same way as before
> [!TIP]
> If you use `v5` or related versions, you need to use `GITHUB_REF_POINT` instead of `GITHUB_REF_NAME` to get the behaviour of the `v4` action.
Before `v5`, the behaviour was the same as the GitHub one except on `pull_request*` workflows ([Ready the full story][issue-104]).
- `${{ 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
```yaml
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`, Git manages the short variables using [`git rev-parse`][git-revparse] behaviour.
The length of a short sha depends on the size of **your repository** and can differ over time.
To manage that moving length, you can use the `short-length` input
- set `7` to reproduce `small repository` behaviour
- set `8` to reproduce `v3` behaviour
> [!WARNING]
> The minimum length is 4, the default is the effective value of the [core.abbrev][git-core-abbrev] configuration variable.
So to reproduce previous behaviour, use
```yaml
steps:
- name: Inject enhanced GitHub environment variables
uses: rlespinasse/github-slug-action@v5
with:
short-length: 8 # Same as v3 and before
```
- [Migrate from v4 to v5](docs/how-to/migrate-v4-to-v5.md) -- `GITHUB_REF_NAME` behaviour changed on pull request events
- [Migrate from v3 to v4](docs/how-to/migrate-v3-to-v4.md) -- Short SHA length is now determined by Git
## 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][naming-conventions]. For a complete list of these, see [Default environment variables][default-environment-variables]. **If you attempt to override the value of one of these default environment variables, the assignment is ignored.**
If a variable starts to be used as a default environment variable, the environment variable may behave differently 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 expressions will serve the behaviour of this action.
This will not occur 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 on the impact.
### An action could not be found at the URI
If your workflow fails on the `Set up job` task with this kind of log
```text
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, following the [end-of-life for a branch](SECURITY.md#end-of-life-of-a-branch) security process, this branch can be deleted.
- `master`, the branch doesn't exist anymore, read more about it on the corresponding issue ([EOL issue][issue-15])
Please, use the current **Major tag** `v5` or a version tag (see [releases pages][releases]) to fix your workflow.
See the [troubleshooting guide](docs/how-to/troubleshooting.md) for common issues and solutions.
## Thanks for talking about us
@@ -257,22 +110,13 @@ In Chinese :cn:
> The next one is you. _Don't hesitate to add yourself to one of these lists._
[examples]: https://github.com/rlespinasse/github-slug-action/tree/v5.x/examples
[custom-variable]: https://github.com/rlespinasse/github-slug-action/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=
[releases]: https://github.com/rlespinasse/github-slug-action/releases
[issue-15]: https://github.com/rlespinasse/github-slug-action/issues/15
[issue-104]: https://github.com/rlespinasse/github-slug-action/issues/104
[slugify-value]: https://github.com/rlespinasse/slugify-value
[shortify-git-revision]: https://github.com/rlespinasse/shortify-git-revision
[git-revparse]: https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt---shortlength
[git-core-abbrev]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreabbrev
[default-environment-variables]: https://docs.github.com/en/actions/reference/workflows-and-actions/variables#default-environment-variables
[dependabot]: https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot
[webhooks-and-events]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads
[naming-conventions]: https://docs.github.com/en/actions/reference/workflows-and-actions/variables#naming-conventions-for-configuration-variables
[article-1]: https://esensconsulting.medium.com/mettre-en-place-une-ci-cd-angular-avec-github-actions-netlify-ca0b59b99ed8
[article-2]: https://michaelheap.com/github-slug-action/

89
docs/explanation/slug-transformation-rules.md Normal file
View File

@@ -0,0 +1,89 @@
# Slug Transformation Rules
This page explains the transformation algorithms used by the GitHub Slug Action, why they exist, and how they differ from each other.
## What is a "slug"?
A slug is a human-readable identifier derived from a string, safe for use in URLs, filenames, DNS labels, and other contexts where special characters are problematic. The term originates from publishing, where a "slug" is a short label used to identify a piece of content.
In CI/CD workflows, branch names, tag names, and repository names often contain characters (`/`, `@`, spaces) that break when used in URLs, Docker tags, Kubernetes labels, or file paths. Slugifying these values makes them safe for such contexts.
## SLUG transformation
The `SLUG` transformation applies the following steps in order:
1. **Lowercase** the entire string
2. **Replace** any character that is not `0-9`, `a-z`, `.`, or `_` with `-`
3. **Remove** leading `-` characters
4. **Truncate** to a maximum length (default: 63 characters)
5. **Remove** trailing `-` characters
### SLUG examples
| Input | Output |
| ----- | ------ |
| `refs/heads/feat/new_feature` | `feat-new-feature` |
| `refs/tags/v1.0.0` | `v1.0.0` |
| `refs/tags/product@1.0.0-rc.2` | `product-1.0.0-rc.2` |
| `octocat/Hello-World` | `octocat-hello-world` |
Note that `.` and `_` are preserved in SLUG output.
## SLUG_URL transformation
The `SLUG_URL` transformation is identical to `SLUG` except that `.` and `_` are also replaced with `-` in step 2. This makes the result safe for use as a URL path segment or subdomain label, where dots and underscores can cause issues.
### SLUG_URL examples
| Input | SLUG | SLUG_URL |
| ----- | ---- | -------- |
| `refs/tags/v1.0.0` | `v1.0.0` | `v1-0-0` |
| `rlespinasse/Hello-World.go` | `rlespinasse-hello-world.go` | `rlespinasse-hello-world-go` |
| `refs/heads/feat/new_feature` | `feat-new-feature` | `feat-new-feature` |
### When to use which
- Use **SLUG** for Docker tags, file paths, and general identifiers (dots and underscores are allowed)
- Use **SLUG_URL** for subdomains, URL path segments, and any context where dots or underscores are problematic
## Why 63 characters?
The default maximum length of 63 comes from the [DNS label length limit](https://www.rfc-editor.org/rfc/rfc1035#section-2.3.4). This is also the maximum length for:
- Kubernetes resource labels
- Many cloud provider resource names
- DNS subdomain components
You can change this limit with the `slug-maxlength` input, or set it to `"nolimit"` to disable truncation entirely.
## SHORT transformation
The `SHORT` transformation truncates Git commit SHAs to a shorter, still-unique prefix. By default, Git determines the optimal length based on your repository size using [`git rev-parse --short`][git-revparse].
| Input | Output |
| ----- | ------ |
| `ffac537e6cbbf934b08745a378932722df287a53` | `ffac537e` |
The length varies by repository because larger repositories need longer prefixes to avoid collisions. You can set a fixed length with the `short-length` input (minimum: 4).
## Case-sensitive variants (_CS)
Every `SLUG` and `SLUG_URL` variable also has a `_CS` (case-sensitive) variant that skips the lowercase step. For example:
| Input | SLUG | SLUG_CS |
| ----- | ---- | ------- |
| `refs/heads/New_Awesome_Product` | `new-awesome-product` | `New-Awesome-Product` |
This is useful when the original casing carries meaning (e.g., product names).
## PART extraction
The `PART` transformation splits a composite value and extracts a portion. Currently used for `GITHUB_REPOSITORY`:
| Input | OWNER_PART | NAME_PART |
| ----- | ---------- | --------- |
| `octocat/Hello-World` | `octocat` | `Hello-World` |
PART variables preserve the original casing. They can be further transformed using SLUG or SLUG_URL suffixes (e.g., `GITHUB_REPOSITORY_OWNER_PART_SLUG`).
[git-revparse]: https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt---shortlength

101
docs/getting-started.md Normal file
View File

@@ -0,0 +1,101 @@
# Getting Started with GitHub Slug Action
This tutorial walks you through adding the GitHub Slug Action to a workflow and using slug variables for the first time.
## Prerequisites
- A GitHub repository with [GitHub Actions enabled](https://docs.github.com/en/actions/using-workflows)
## Step 1: Add the action to your workflow
Create or edit a workflow file (e.g., `.github/workflows/deploy.yml`) and add the action after checking out your code:
```yaml
name: Deploy
on: push
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Inject enhanced GitHub environment variables
uses: rlespinasse/github-slug-action@v5
```
> [!TIP]
> The `actions/checkout` step is recommended so that Git can determine the optimal short SHA length for your repository. It is not strictly required for slug variables.
## Step 2: Use slug variables in subsequent steps
After the action runs, all slug variables are available as environment variables. Add a step to use them:
```yaml
- name: Print slug variables
run: |
echo "Repository slug: $GITHUB_REPOSITORY_SLUG"
echo "Branch slug: $GITHUB_REF_SLUG"
echo "Short SHA: $GITHUB_SHA_SHORT"
shell: bash
```
For a branch named `feat/new_feature` on repository `octocat/Hello-World`, this outputs:
```text
Repository slug: octocat-hello-world
Branch slug: feat-new-feature
Short SHA: ffac537e
```
## Step 3: Use a slug variable for a practical purpose
A common use case is naming deployment previews with a URL-safe branch identifier:
```yaml
- name: Deploy preview
run: |
echo "Deploying to https://${GITHUB_REF_SLUG_URL}.preview.example.com"
shell: bash
```
The `SLUG_URL` variant replaces dots and underscores too, making it safe for subdomains.
## Complete workflow
Here is the full workflow file:
```yaml
name: Deploy
on: push
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Inject enhanced GitHub environment variables
uses: rlespinasse/github-slug-action@v5
- name: Deploy preview
run: |
echo "Deploying to https://${GITHUB_REF_SLUG_URL}.preview.example.com"
echo "Commit: ${GITHUB_SHA_SHORT}"
shell: bash
```
## What you learned
- **SLUG** variables convert values to lowercase and replace special characters with `-`
- **SLUG_URL** variables also replace `.` and `_`, making values safe for URLs and subdomains
- **SHORT** variables shorten SHA commit hashes
- All variables are exposed as environment variables for use in subsequent steps
## Next steps
- [How-to guides](how-to/) for specific configuration tasks (prefixes, custom lengths, URL usage)
- [Variable reference](reference/variables.md) for the complete list of available variables
- [Slug transformation rules](explanation/slug-transformation-rules.md) to understand how transformations work

96
docs/github-variables.md
View File

@@ -1,97 +1,3 @@
# Available GitHub Variables
All `GitHub` variables availables in your workflow in addition of ones exposed by this Action
## Table of Contents
- [Available GitHub Variables](#available-github-variables)
- [Table of Contents](#table-of-contents)
- [Default environment variables](#default-environment-variables)
- [Action-managed Environment Variables](#action-managed-environment-variables)
- [Variables from events](#variables-from-events)
- [Action-managed Event Variables](#action-managed-event-variables)
- [create](#create)
- [delete](#delete)
- [pull\_request](#pull_request)
- [pull\_request\_review](#pull_request_review)
- [pull\_request\_review\_comment](#pull_request_review_comment)
- [pull\_request\_target](#pull_request_target)
## Default environment variables
Read the official documentation about [Default environment variables][1].
### Action-managed Environment Variables
| Action-managed Variables | Can be suffix by |
| ------------------------ | --------------- |
| GITHUB_REPOSITORY | `_SLUG`, `_SLUG_URL` |
| GITHUB_REF | `_SLUG`, `_SLUG_URL` |
| GITHUB_REF_NAME | `_SLUG`, `_SLUG_URL` |
| GITHUB_HEAD_REF | `_SLUG`, `_SLUG_URL` |
| GITHUB_BASE_REF | `_SLUG`, `_SLUG_URL` |
| GITHUB_SHA | `_SHORT` |
## Variables from events
Read the official documentation about [Events that trigger workflows][2].
### Action-managed Event Variables
#### create
Checkout [create][3] webhook payload content
| Action-managed Variables | Available as |
| ------------------------ | ------------ |
| github.event.ref | GITHUB_EVENT_REF_SLUG |
| github.event.ref | GITHUB_EVENT_REF_SLUG_URL |
#### delete
Checkout [delete][4] webhook payload content
| Action-managed Variables | Available as |
| ------------------------ | ------------ |
| github.event.ref | GITHUB_EVENT_REF_SLUG |
| github.event.ref | GITHUB_EVENT_REF_SLUG_URL |
#### pull_request
Checkout [pull_request][5] webhook payload content
| Action-managed Variables | Available as |
| ------------------------ | ------------ |
| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
#### pull_request_review
Checkout [pull_request_review][6] webhook payload content
| Action-managed Variables | Available as |
| ------------------------ | ------------ |
| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
#### pull_request_review_comment
Checkout [pull_request_review_comment][7] webhook payload content
| Action-managed Variables | Available as |
| ------------------------ | ------------ |
| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
#### pull_request_target
Checkout [pull_request][5] webhook payload content
| Action-managed Variables | Available as |
| ------------------------ | ------------ |
| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
[1]: https://docs.github.com/en/actions/reference/environment-variables#default-environment-variables
[2]: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
[3]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#create
[4]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#delete
[5]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#pull_request
[6]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#pull_request_review
[7]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#pull_request_review_comment
This page has moved to [reference/github-variables.md](reference/github-variables.md).

45
docs/how-to/configure-short-length.md Normal file
View File

@@ -0,0 +1,45 @@
# Configure the length of short SHA values
Set a specific length for shortened commit SHA values instead of letting Git determine it automatically.
## Usage
```yaml
steps:
- name: Inject enhanced GitHub environment variables
uses: rlespinasse/github-slug-action@v5
with:
short-length: 7
```
## Common values
| Value | Use case |
| ----- | -------- |
| _(empty)_ | Let Git decide based on repository size (default) |
| `7` | Common "small repository" length |
| `8` | Reproduce `v3` action behaviour |
| `4` | Minimum allowed length |
## Letting Git decide (default)
When `short-length` is left empty, the action uses Git's [`git rev-parse --short`][git-revparse] behaviour. The length depends on the size of your repository and may change over time as the repository grows.
> [!WARNING]
> If you leave `short-length` empty, you need to checkout the source first so Git can determine the length:
>
> ```yaml
> steps:
> - uses: actions/checkout@v6
> - uses: rlespinasse/github-slug-action@v5
> ```
>
> Without a checkout step, the action falls back to the effective value of the [`core.abbrev`][git-core-abbrev] Git configuration variable, or `7` if unavailable.
## See also
- [Inputs reference](../reference/inputs.md) for the full specification
- [SHORT transformation](../explanation/slug-transformation-rules.md#short-transformation) for how short values are computed
[git-revparse]: https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt---shortlength
[git-core-abbrev]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreabbrev

33
docs/how-to/configure-slug-maxlength.md Normal file
View File

@@ -0,0 +1,33 @@
# Configure the maximum length for slug values
Change the maximum length of slugified values. The default is 63 characters (the DNS label length limit).
## Usage
```yaml
steps:
- name: Inject enhanced GitHub environment variables
uses: rlespinasse/github-slug-action@v5
with:
slug-maxlength: 80
```
## Disable the length limit
Set `slug-maxlength` to `"nolimit"` to disable truncation entirely:
```yaml
steps:
- name: Inject enhanced GitHub environment variables
uses: rlespinasse/github-slug-action@v5
with:
slug-maxlength: nolimit
```
> [!WARNING]
> The `slug-maxlength` input must not be empty. If left empty, the action will fail during preflight validation.
## See also
- [Inputs reference](../reference/inputs.md) for the full specification
- [Why 63 characters?](../explanation/slug-transformation-rules.md#why-63-characters) for the rationale behind the default

30
docs/how-to/migrate-v3-to-v4.md Normal file
View File

@@ -0,0 +1,30 @@
# Migrate from v3 to v4
The main breaking change in v4 is that **short SHA length** is now determined by Git instead of being fixed at 8 characters.
## What changed
Since v4, Git manages the short variables using [`git rev-parse`][git-revparse] behaviour. The length of a short SHA depends on the size of your repository and can change over time as the repository grows.
## How to migrate
To reproduce the previous fixed-length behaviour, set `short-length` to `8`:
```yaml
steps:
- name: Inject enhanced GitHub environment variables
uses: rlespinasse/github-slug-action@v5
with:
short-length: 8 # Same as v3 and before
```
Other options:
- Set `7` to reproduce small repository behaviour
- Leave empty to let Git decide (recommended)
> [!WARNING]
> The minimum length is `4`. The default is the effective value of the [`core.abbrev`][git-core-abbrev] Git configuration variable.
[git-revparse]: https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt---shortlength
[git-core-abbrev]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreabbrev

30
docs/how-to/migrate-v4-to-v5.md Normal file
View File

@@ -0,0 +1,30 @@
# Migrate from v4 to v5
The main breaking change in v5 is that **GITHUB_REF_NAME** slug variables now match GitHub's native behaviour on `pull_request*` events.
## What changed
Before v5, the action overrode `GITHUB_REF_NAME` to always contain the branch name, even on pull request events. Starting with v5, `GITHUB_REF_NAME` on pull request events contains `<PR-number>/merge` (matching GitHub's native behaviour). Read the [full story][issue-104].
## How to migrate
If you used `GITHUB_REF_NAME_SLUG` to get the branch name on pull request events, switch to `GITHUB_REF_POINT_SLUG`:
```yaml
steps:
- name: Inject enhanced GitHub environment variables
uses: rlespinasse/github-slug-action@v5
- run: |
echo "Branch Name: ${GITHUB_REF_POINT}"
shell: bash
```
`GITHUB_REF_POINT` provides the branch name on pull request events (via `GITHUB_HEAD_REF`) and the ref name on all other events (via `GITHUB_REF_NAME`). All slug suffixes are available: `GITHUB_REF_POINT_SLUG`, `GITHUB_REF_POINT_SLUG_URL`, etc.
## Expression syntax
- `${{ env.GITHUB_REF_POINT }}` and `$GITHUB_REF_POINT` both serve the action's behaviour
- `${{ env.GITHUB_REF_NAME }}` serves the action's behaviour
- `$GITHUB_REF_NAME` serves GitHub Action's native behaviour
[issue-104]: https://github.com/rlespinasse/github-slug-action/issues/104

56
docs/how-to/troubleshooting.md Normal file
View File

@@ -0,0 +1,56 @@
# 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][naming-conventions]. For a complete list of these, see [Default environment variables][default-environment-variables]. **If you attempt to override the value of one of these default environment variables, the assignment is ignored.**
If a variable starts to be used as a default environment variable by GitHub, the behaviour may differ depending on how you reference it:
- `${{ env.GITHUB_AWESOME_VARIABLE }}` serves the behaviour of this action
- `$GITHUB_AWESOME_VARIABLE` serves the behaviour of GitHub Actions
If both expressions return the same value, the variable is not affected. Use the [`prefix` input](use-prefix.md) to avoid this issue entirely.
> [!IMPORTANT]
> If detected, the maintainers of this action will choose the best course of action depending on the impact.
## An action could not be found at the URI
If your workflow fails on the `Set up job` task with this kind of log:
```text
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: following the [end-of-life for a branch](../../SECURITY.md#end-of-life-of-a-branch) security process, this branch may have been deleted.
- `master`: this branch no longer exists. Read more on the corresponding issue ([EOL issue][issue-15]).
Use the current **major tag** `v5` or a specific version tag (see [releases][releases]) to fix your workflow.
## Short variables are empty or have unexpected length
If `GITHUB_SHA_SHORT` is empty or shorter than expected, ensure you have checked out your repository before the action runs:
```yaml
steps:
- uses: actions/checkout@v6
- uses: rlespinasse/github-slug-action@v5
```
Without a checkout, Git cannot determine the optimal short length for your repository. Alternatively, set a fixed `short-length` to avoid depending on the checkout:
```yaml
steps:
- uses: rlespinasse/github-slug-action@v5
with:
short-length: 7
```
[naming-conventions]: https://docs.github.com/en/actions/reference/workflows-and-actions/variables#naming-conventions-for-configuration-variables
[default-environment-variables]: https://docs.github.com/en/actions/reference/workflows-and-actions/variables#default-environment-variables
[issue-15]: https://github.com/rlespinasse/github-slug-action/issues/15
[releases]: https://github.com/rlespinasse/github-slug-action/releases

26
docs/how-to/use-prefix.md Normal file
View File

@@ -0,0 +1,26 @@
# Use a prefix for generated variables
Add a prefix to all generated environment variables to avoid naming conflicts with [GitHub's default environment variables](https://docs.github.com/en/actions/reference/workflows-and-actions/variables#default-environment-variables).
## Usage
```yaml
steps:
- name: Inject enhanced GitHub environment variables
uses: rlespinasse/github-slug-action@v5
with:
prefix: CI_
```
With this configuration, variables are named `CI_GITHUB_REPOSITORY_SLUG`, `CI_GITHUB_REF_SLUG`, `CI_GITHUB_SHA_SHORT`, etc.
## When to use a prefix
- When a variable name collides with a GitHub default environment variable (the assignment would be silently ignored without a prefix)
- When you want to distinguish slug variables from other environment variables in your workflow
- As a preventive measure against future GitHub environment variable additions
## See also
- [Inputs reference](../reference/inputs.md) for the full `prefix` input specification
- [Troubleshooting](troubleshooting.md#one-of-the-environment-variables-doesnt-work-as-intended) for details on variable name collisions

36
docs/how-to/use-slugs-in-urls.md Normal file
View File

@@ -0,0 +1,36 @@
# Use slug variables in URLs
Use `SLUG_URL` variables (not `SLUG`) when building URLs, because `SLUG_URL` also replaces dots and underscores with hyphens, making values safe for subdomains and URL paths.
## As a subdomain
```yaml
steps:
- uses: actions/checkout@v6
- uses: rlespinasse/github-slug-action@v5
- run: |
./deploy-application.sh --url "https://${{ env.GITHUB_REF_SLUG_URL }}.staging.app.example.com"
```
For a branch `feat/new_feature`, this produces `https://feat-new-feature.staging.app.example.com`.
## As a URL path segment
```yaml
steps:
- uses: actions/checkout@v6
- uses: rlespinasse/github-slug-action@v5
- run: |
./deploy-application.sh --url "https://staging.app.example.com/${{ env.GITHUB_REF_SLUG_URL }}"
```
## Why SLUG_URL instead of SLUG?
The `SLUG` transformation preserves `.` and `_` characters. In a subdomain like `v1.0.0.staging.example.com`, the dots from the version tag would create invalid DNS resolution. `SLUG_URL` replaces them: `v1-0-0.staging.example.com`.
See [Slug transformation rules](../explanation/slug-transformation-rules.md#slug_url-transformation) for the full comparison.
## See also
- [Full example workflow](../../examples/url-use.yml)
- [Variable reference](../reference/variables.md) for all available `SLUG_URL` variables

27
docs/partial-variables.md
View File

@@ -1,28 +1,3 @@
# Partial Variables
## Table of Contents
- [Partial Variables](#partial-variables)
- [Table of Contents](#table-of-contents)
- [GITHUB\_REPOSITORY\_OWNER\_PART](#github_repository_owner_part)
- [GITHUB\_REPOSITORY\_NAME\_PART](#github_repository_name_part)
## GITHUB_REPOSITORY_OWNER_PART
Owner part of the environment variable **GITHUB_REPOSITORY**
| GITHUB_REPOSITORY | GITHUB_REPOSITORY_OWNER_PART |
| ----------------- | ---------------------------- |
| octocat/Hello-World | octocat |
| rlespinasse/Hello-World.go | rlespinasse |
| AnotherPerson/SomeRepository | AnotherPerson |
## GITHUB_REPOSITORY_NAME_PART
Repository name part of the environment variable **GITHUB_REPOSITORY**
| GITHUB_REPOSITORY | GITHUB_REPOSITORY_NAME_PART |
| ----------------- | --------------------------- |
| octocat/Hello-World | Hello-World |
| rlespinasse/Hello-World.go | Hello-World.go |
| AnotherPerson/SomeRepository | SomeRepository |
This page has moved to [reference/variables.md](reference/variables.md#partial-variables).

87
docs/reference/github-variables.md Normal file
View File

@@ -0,0 +1,87 @@
# Available GitHub Variables
All GitHub variables available in your workflow in addition to ones exposed by this action.
## Default Environment Variables
Read the official documentation about [Default environment variables][1].
### Action-managed Environment Variables
| Action-managed Variables | Can be suffixed by |
| ------------------------ | ------------------ |
| GITHUB_REPOSITORY | `_SLUG`, `_SLUG_URL` |
| GITHUB_REF | `_SLUG`, `_SLUG_URL` |
| GITHUB_REF_NAME | `_SLUG`, `_SLUG_URL` |
| GITHUB_HEAD_REF | `_SLUG`, `_SLUG_URL` |
| GITHUB_BASE_REF | `_SLUG`, `_SLUG_URL` |
| GITHUB_SHA | `_SHORT` |
## Variables from Events
Read the official documentation about [Events that trigger workflows][2].
### Action-managed Event Variables
#### create
Checkout [create][3] webhook payload content
| Action-managed Variables | Available as |
| ------------------------ | ------------ |
| github.event.ref | GITHUB_EVENT_REF_SLUG |
| github.event.ref | GITHUB_EVENT_REF_SLUG_URL |
#### delete
Checkout [delete][4] webhook payload content
| Action-managed Variables | Available as |
| ------------------------ | ------------ |
| github.event.ref | GITHUB_EVENT_REF_SLUG |
| github.event.ref | GITHUB_EVENT_REF_SLUG_URL |
#### pull_request
Checkout [pull_request][5] webhook payload content
| Action-managed Variables | Available as |
| ------------------------ | ------------ |
| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
#### pull_request_review
Checkout [pull_request_review][6] webhook payload content
| Action-managed Variables | Available as |
| ------------------------ | ------------ |
| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
#### pull_request_review_comment
Checkout [pull_request_review_comment][7] webhook payload content
| Action-managed Variables | Available as |
| ------------------------ | ------------ |
| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
#### pull_request_target
Checkout [pull_request][5] webhook payload content
| Action-managed Variables | Available as |
| ------------------------ | ------------ |
| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
## See also
- [Variable reference](variables.md) for transformation examples
- [Slug transformation rules](../explanation/slug-transformation-rules.md) for how transformations work
[1]: https://docs.github.com/en/actions/reference/environment-variables#default-environment-variables
[2]: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
[3]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#create
[4]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#delete
[5]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#pull_request
[6]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#pull_request_review
[7]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#pull_request_review_comment

23
docs/reference/inputs.md Normal file
View File

@@ -0,0 +1,23 @@
# Inputs Reference
The GitHub Slug Action accepts the following inputs in the `with:` block.
| Input | Required | Default | Description |
| ----- | -------- | ------- | ----------- |
| `prefix` | No | `""` | Value prepended to each generated variable name. For example, `prefix: CI_` produces `CI_GITHUB_REPOSITORY_SLUG` instead of `GITHUB_REPOSITORY_SLUG`. |
| `slug-maxlength` | Yes | `63` | Maximum length of slugified values. Accepts a number or `"nolimit"` to disable truncation. Must not be empty. |
| `short-length` | No | _(Git default)_ | Length of shortened SHA values. Minimum `4`. When empty, Git determines the length based on your repository size using [`git rev-parse`][git-revparse]. |
## Notes
- When `short-length` is left empty, the action uses the effective value of the [`core.abbrev`][git-core-abbrev] Git configuration variable. This requires your repository to be checked out first (via `actions/checkout`).
- The `slug-maxlength` default of `63` matches the DNS label length limit, which is also the maximum length for Kubernetes labels.
## See also
- [How to use a prefix](../how-to/use-prefix.md)
- [How to configure slug max length](../how-to/configure-slug-maxlength.md)
- [How to configure short length](../how-to/configure-short-length.md)
[git-revparse]: https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt---shortlength
[git-core-abbrev]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreabbrev

312
docs/reference/variables.md Normal file
View File

@@ -0,0 +1,312 @@
# Variable Reference
Complete reference for all environment variables generated by the GitHub Slug Action.
> [!TIP]
> All slug and slug-url variables are also available in case-sensitive (`_CS`) variants. See [Case-sensitive variants](#case-sensitive-variants).
## Summary
| Variable | Type | Description |
| -------- | ---- | ----------- |
| `GITHUB_REF_POINT` | Enhanced | Branch or tag name (consistent across event types) |
| `GITHUB_REPOSITORY_OWNER_PART` | Partial | Owner extracted from `GITHUB_REPOSITORY` |
| `GITHUB_REPOSITORY_NAME_PART` | Partial | Repository name extracted from `GITHUB_REPOSITORY` |
| `GITHUB_REPOSITORY_SLUG` | Slug | Slugified owner/repository name |
| `GITHUB_REPOSITORY_OWNER_PART_SLUG` | Slug | Slugified owner name |
| `GITHUB_REPOSITORY_NAME_PART_SLUG` | Slug | Slugified repository name |
| `GITHUB_REF_SLUG` | Slug | Slugified branch or tag ref |
| `GITHUB_REF_NAME_SLUG` | Slug | Slugified branch or tag name |
| `GITHUB_HEAD_REF_SLUG` | Slug | Slugified PR head branch |
| `GITHUB_BASE_REF_SLUG` | Slug | Slugified PR base branch |
| `GITHUB_EVENT_REF_SLUG` | Slug | Slugified webhook ref |
| `GITHUB_REPOSITORY_SLUG_URL` | Slug URL | URL-safe owner/repository name |
| `GITHUB_REPOSITORY_OWNER_PART_SLUG_URL` | Slug URL | URL-safe owner name |
| `GITHUB_REPOSITORY_NAME_PART_SLUG_URL` | Slug URL | URL-safe repository name |
| `GITHUB_REF_SLUG_URL` | Slug URL | URL-safe branch or tag ref |
| `GITHUB_REF_NAME_SLUG_URL` | Slug URL | URL-safe branch or tag name |
| `GITHUB_HEAD_REF_SLUG_URL` | Slug URL | URL-safe PR head branch |
| `GITHUB_BASE_REF_SLUG_URL` | Slug URL | URL-safe PR base branch |
| `GITHUB_EVENT_REF_SLUG_URL` | Slug URL | URL-safe webhook ref |
| `GITHUB_SHA_SHORT` | Short | Shortened commit SHA |
| `GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT` | Short | Shortened PR head commit SHA |
---
## Enhanced Variables
### GITHUB_REF_POINT
The reference name (branch or tag), consistent across all event types:
- Uses `GITHUB_HEAD_REF` in [`pull_request*`][webhooks] event contexts
- Uses `GITHUB_REF_NAME` in all other event contexts
This provides a stable branch name regardless of event type. On pull request events, `GITHUB_REF_NAME` contains `<PR#>/merge`, while `GITHUB_REF_POINT` contains the actual branch name.
Available with all slug suffixes: `GITHUB_REF_POINT_SLUG`, `GITHUB_REF_POINT_SLUG_URL`, `GITHUB_REF_POINT_SLUG_CS`, `GITHUB_REF_POINT_SLUG_URL_CS`.
---
## Partial Variables
### GITHUB_REPOSITORY_OWNER_PART
Owner part of the environment variable **GITHUB_REPOSITORY**.
| GITHUB_REPOSITORY | GITHUB_REPOSITORY_OWNER_PART |
| ----------------- | ---------------------------- |
| octocat/Hello-World | octocat |
| rlespinasse/Hello-World.go | rlespinasse |
| AnotherPerson/SomeRepository | AnotherPerson |
### GITHUB_REPOSITORY_NAME_PART
Repository name part of the environment variable **GITHUB_REPOSITORY**.
| GITHUB_REPOSITORY | GITHUB_REPOSITORY_NAME_PART |
| ----------------- | --------------------------- |
| octocat/Hello-World | Hello-World |
| rlespinasse/Hello-World.go | Hello-World.go |
| AnotherPerson/SomeRepository | SomeRepository |
---
## Slug Variables
Slug variables apply the [SLUG transformation](../explanation/slug-transformation-rules.md#slug-transformation): lowercase, replace special characters with `-`, preserve `.` and `_`, truncate to max length.
### GITHUB_REPOSITORY_SLUG
Slug of **GITHUB_REPOSITORY** -- the owner and repository name.
| GITHUB_REPOSITORY | GITHUB_REPOSITORY_SLUG |
| ----------------- | ---------------------- |
| octocat/Hello-World | octocat-hello-world |
| rlespinasse/Hello-World.go | rlespinasse-hello-world.go |
| AnotherPerson/SomeRepository | anotherperson-somerepository |
### GITHUB_REPOSITORY_OWNER_PART_SLUG
Slug of **GITHUB_REPOSITORY_OWNER_PART** -- the owner name.
| GITHUB_REPOSITORY_OWNER_PART | GITHUB_REPOSITORY_OWNER_PART_SLUG |
| ---------------------------- | --------------------------------- |
| octocat | octocat |
| rlespinasse | rlespinasse |
| AnotherPerson | anotherperson |
### GITHUB_REPOSITORY_NAME_PART_SLUG
Slug of **GITHUB_REPOSITORY_NAME_PART** -- the repository name.
| GITHUB_REPOSITORY_NAME_PART | GITHUB_REPOSITORY_NAME_PART_SLUG |
| --------------------------- | -------------------------------- |
| Hello-World | hello-world |
| Hello-World.go | hello-world.go |
| SomeRepository | somerepository |
### GITHUB_REF_SLUG
Slug of **GITHUB_REF** -- the branch or tag ref that triggered the workflow.
_If neither a branch or tag is available for the event type, the variable will not exist._
| GITHUB_REF | GITHUB_REF_SLUG |
| ---------- | --------------- |
| refs/heads/main | main |
| refs/heads/feat/new_feature | feat-new-feature |
| refs/tags/v1.0.0 | v1.0.0 |
| refs/tags/product@1.0.0-rc.2 | product-1.0.0-rc.2 |
| refs/heads/New_Awesome_Product | new-awesome-product |
### GITHUB_REF_NAME_SLUG
Slug of **GITHUB_REF_NAME** -- the branch or tag name shown on GitHub.
_If neither a branch or tag is available for the event type, the variable will not exist._
| GITHUB_REF_NAME | GITHUB_REF_NAME_SLUG |
| --------------- | -------------------- |
| main | main |
| feat/new_feature | feat-new-feature |
| v1.0.0 | v1.0.0 |
| product@1.0.0-rc.2 | product-1.0.0-rc.2 |
| New_Awesome_Product | new-awesome-product |
| 42/merge | 42-merge |
### GITHUB_HEAD_REF_SLUG
Slug of **GITHUB_HEAD_REF** -- the branch of the head repository.
_Only set for [`pull_request*`][webhooks] events and forked repositories._
| GITHUB_HEAD_REF | GITHUB_HEAD_REF_SLUG |
| --------------- | -------------------- |
| main | main |
| feat/new_feature | feat-new-feature |
| New_Awesome_Product | new-awesome-product |
### GITHUB_BASE_REF_SLUG
Slug of **GITHUB_BASE_REF** -- the branch of the base repository.
_Only set for [`pull_request*`][webhooks] events and forked repositories._
| GITHUB_BASE_REF | GITHUB_BASE_REF_SLUG |
| --------------- | -------------------- |
| main | main |
| feat/new_feature | feat-new-feature |
| New_Awesome_Product | new-awesome-product |
### GITHUB_EVENT_REF_SLUG
Slug of **github.event.ref** -- the Git reference resource associated to the triggered webhook.
_Only set for [`create` and `delete`][webhooks] events._
| github.event.ref | GITHUB_EVENT_REF_SLUG |
| ---------------- | --------------------- |
| main | main |
| feat/new_feature | feat-new-feature |
| New_Awesome_Product | new-awesome-product |
---
## URL-Safe Slug Variables
URL-safe slug variables apply the [SLUG_URL transformation](../explanation/slug-transformation-rules.md#slug_url-transformation): same as SLUG but `.` and `_` are also replaced with `-`.
### GITHUB_REPOSITORY_SLUG_URL
URL-safe slug of **GITHUB_REPOSITORY** -- the owner and repository name.
| GITHUB_REPOSITORY | GITHUB_REPOSITORY_SLUG_URL |
| ----------------- | -------------------------- |
| octocat/Hello-World | octocat-hello-world |
| rlespinasse/Hello-World.go | rlespinasse-hello-world-go |
| AnotherPerson/SomeRepository | anotherperson-somerepository |
### GITHUB_REPOSITORY_OWNER_PART_SLUG_URL
URL-safe slug of **GITHUB_REPOSITORY_OWNER_PART** -- the owner name.
| GITHUB_REPOSITORY_OWNER_PART | GITHUB_REPOSITORY_OWNER_PART_SLUG_URL |
| ---------------------------- | ------------------------------------- |
| octocat | octocat |
| rlespinasse | rlespinasse |
| AnotherPerson | anotherperson |
### GITHUB_REPOSITORY_NAME_PART_SLUG_URL
URL-safe slug of **GITHUB_REPOSITORY_NAME_PART** -- the repository name.
| GITHUB_REPOSITORY_NAME_PART | GITHUB_REPOSITORY_NAME_PART_SLUG_URL |
| --------------------------- | ------------------------------------ |
| Hello-World | hello-world |
| Hello-World.go | hello-world-go |
| SomeRepository | somerepository |
### GITHUB_REF_SLUG_URL
URL-safe slug of **GITHUB_REF** -- the branch or tag ref that triggered the workflow.
_If neither a branch or tag is available for the event type, the variable will not exist._
| GITHUB_REF | GITHUB_REF_SLUG_URL |
| ---------- | ------------------- |
| refs/heads/main | main |
| refs/heads/feat/new_feature | feat-new-feature |
| refs/tags/v1.0.0 | v1-0-0 |
| refs/pull/42/merge | 42-merge |
| refs/tags/product@1.0.0-rc.2 | product-1-0-0-rc-2 |
| refs/heads/New_Awesome_Product | new-awesome-product |
### GITHUB_REF_NAME_SLUG_URL
URL-safe slug of **GITHUB_REF_NAME** -- the branch or tag name shown on GitHub.
_If neither a branch or tag is available for the event type, the variable will not exist._
| GITHUB_REF_NAME | GITHUB_REF_NAME_SLUG_URL |
| --------------- | ------------------------ |
| main | main |
| feat/new_feature | feat-new-feature |
| v1.0.0 | v1-0-0 |
| 42/merge | 42-merge |
| product@1.0.0-rc.2 | product-1-0-0-rc-2 |
| New_Awesome_Product | new-awesome-product |
### GITHUB_HEAD_REF_SLUG_URL
URL-safe slug of **GITHUB_HEAD_REF** -- the branch of the head repository.
_Only set for [`pull_request*`][webhooks] events and forked repositories._
| GITHUB_HEAD_REF | GITHUB_HEAD_REF_SLUG_URL |
| --------------- | ------------------------ |
| main | main |
| feat/new_feature | feat-new-feature |
| New_Awesome_Product | new-awesome-product |
### GITHUB_BASE_REF_SLUG_URL
URL-safe slug of **GITHUB_BASE_REF** -- the branch of the base repository.
_Only set for [`pull_request*`][webhooks] events and forked repositories._
| GITHUB_BASE_REF | GITHUB_BASE_REF_SLUG_URL |
| --------------- | ------------------------ |
| main | main |
| feat/new_feature | feat-new-feature |
| New_Awesome_Product | new-awesome-product |
### GITHUB_EVENT_REF_SLUG_URL
URL-safe slug of **github.event.ref** -- the Git reference resource associated to the triggered webhook.
_Only set for [`create` and `delete`][webhooks] events._
| github.event.ref | GITHUB_EVENT_REF_SLUG_URL |
| ---------------- | ------------------------- |
| main | main |
| feat/new_feature | feat-new-feature |
| New_Awesome_Product | new-awesome-product |
---
## Short Variables
### GITHUB_SHA_SHORT
Shortened **GITHUB_SHA** -- the commit SHA that triggered the workflow.
| GITHUB_SHA | GITHUB_SHA_SHORT |
| ---------- | ---------------- |
| ffac537e6cbbf934b08745a378932722df287a53 | ffac537e |
### GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT
Shortened value of `github.event.pull_request.head.sha` -- the last commit on the pull request that triggered the workflow.
| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
| ---------------------------------- | ---------------------------------------- |
| ffac537e6cbbf934b08745a378932722df287a53 | ffac537e |
---
## Case-Sensitive Variants
All slug and slug-url variables have a `_CS` suffix variant that preserves the original casing. The `_CS` variant applies the same transformation but skips the lowercase step.
| Standard | Case-Sensitive |
| -------- | -------------- |
| `GITHUB_REPOSITORY_SLUG` | `GITHUB_REPOSITORY_SLUG_CS` |
| `GITHUB_REPOSITORY_SLUG_URL` | `GITHUB_REPOSITORY_SLUG_URL_CS` |
| `GITHUB_REF_SLUG` | `GITHUB_REF_SLUG_CS` |
| `GITHUB_REF_SLUG_URL` | `GITHUB_REF_SLUG_URL_CS` |
| _(and so on for all slug/slug-url variables)_ | |
Example:
| Input | SLUG | SLUG_CS |
| ----- | ---- | ------- |
| `refs/heads/New_Awesome_Product` | `new-awesome-product` | `New-Awesome-Product` |
---
## Variable Availability by Event
Not all variables are set for every event type. See [GitHub variables by event](github-variables.md) for the full matrix.
[webhooks]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads

26
docs/short-variables.md
View File

@@ -1,27 +1,3 @@
# Short Variables
## Table of Contents
- [Short Variables](#short-variables)
- [Table of Contents](#table-of-contents)
- [GITHUB\_SHA\_SHORT](#github_sha_short)
- [GITHUB\_EVENT\_PULL\_REQUEST\_HEAD\_SHA\_SHORT](#github_event_pull_request_head_sha_short)
## GITHUB_SHA_SHORT
Short the environment variable **GITHUB_SHA**
The commit SHA that triggered the workflow
| GITHUB_SHA | GITHUB_SHA_SHORT |
| ---------- | ---------------- |
| ffac537e6cbbf934b08745a378932722df287a53 | ffac537e |
## GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT
Short the value of `github.event.pull_request.head.sha` that represents the last commit
used for triggering an action for a pull request.
| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
| ---------------------------------- | ---------------------------------------- |
| ffac537e6cbbf934b08745a378932722df287a53 | ffac537e |
This page has moved to [reference/variables.md](reference/variables.md#short-variables).

122
docs/slug-url-variables.md
View File

@@ -1,123 +1,3 @@
# Slug URL Variables
## Table of Contents
- [Slug URL Variables](#slug-url-variables)
- [Table of Contents](#table-of-contents)
- [GITHUB\_REPOSITORY\_SLUG\_URL](#github_repository_slug_url)
- [GITHUB\_REPOSITORY\_OWNER\_PART\_SLUG\_URL](#github_repository_owner_part_slug_url)
- [GITHUB\_REPOSITORY\_NAME\_PART\_SLUG\_URL](#github_repository_name_part_slug_url)
- [GITHUB\_REF\_SLUG\_URL](#github_ref_slug_url)
- [GITHUB\_REF\_NAME\_SLUG\_URL](#github_ref_name_slug_url)
- [GITHUB\_HEAD\_REF\_SLUG\_URL](#github_head_ref_slug_url)
- [GITHUB\_BASE\_REF\_SLUG\_URL](#github_base_ref_slug_url)
- [GITHUB\_EVENT\_REF\_SLUG\_URL](#github_event_ref_slug_url)
## GITHUB_REPOSITORY_SLUG_URL
Slug URL the environment variable **GITHUB_REPOSITORY**
The owner and repository name.
| GITHUB_REPOSITORY | GITHUB_REPOSITORY_SLUG_URL |
| ----------------- | ---------------------------- |
| octocat/Hello-World | octocat-hello-world |
| rlespinasse/Hello-World.go | rlespinasse-hello-world-go |
| AnotherPerson/SomeRepository | anotherperson-somerepository |
## GITHUB_REPOSITORY_OWNER_PART_SLUG_URL
Slug URL the environment variable [GITHUB_REPOSITORY_OWNER_PART](partial-variables.md#github_repository_owner_part)
The Owner part of **GITHUB_REPOSITORY** variable.
| GITHUB_REPOSITORY_OWNER_PART | GITHUB_REPOSITORY_OWNER_PART_SLUG_URL |
| ---------------------------- | ------------------------------------- |
| octocat | octocat |
| rlespinasse | rlespinasse |
| AnotherPerson | anotherperson |
## GITHUB_REPOSITORY_NAME_PART_SLUG_URL
Slug URL the environment variable [GITHUB_REPOSITORY_NAME_PART](partial-variables.md#github_repository_name_part)
The Repository name part of **GITHUB_REPOSITORY** variable.
| GITHUB_REPOSITORY_NAME_PART | GITHUB_REPOSITORY_NAME_PART_SLUG_URL |
| --------------------------- | ------------------------------------ |
| Hello-World | hello-world |
| Hello-World.go | hello-world-go |
| SomeRepository | somerepository |
## GITHUB_REF_SLUG_URL
Slug URL the environment variable **GITHUB_REF**
The branch or tag ref that triggered the workflow.
_If neither a branch or tag is available for the event type, the variable will not exist._
| GITHUB_REF | GITHUB_REF_SLUG_URL |
| ---------- | ------------------- |
| refs/heads/main | main |
| refs/heads/feat/new_feature | feat-new-feature |
| refs/tags/v1.0.0 | v1-0-0 |
| refs/pull/42/merge | 42-merge |
| refs/tags/product@1.0.0-rc.2 | product-1-0-0-rc-2 |
| refs/heads/New_Awesome_Product | new-awesome-product |
## GITHUB_REF_NAME_SLUG_URL
Slug URL the environment variable **GITHUB_REF_NAME**
The branch or tag ref that triggered the workflow.
_If neither a branch or tag is available for the event type, the variable will not exist._
| GITHUB_REF_NAME | GITHUB_REF_SLUG_URL |
| --------------- | ------------------- |
| refs/heads/main | main |
| refs/heads/feat/new_feature | feat-new-feature |
| refs/tags/v1.0.0 | v1-0-0 |
| refs/pull/42/merge | 42-merge |
| refs/tags/product@1.0.0-rc.2 | product-1-0-0-rc-2 |
| refs/heads/New_Awesome_Product | new-awesome-product |
## GITHUB_HEAD_REF_SLUG_URL
Slug URL the environment variable **GITHUB_HEAD_REF**
The branch of the head repository.
_Only set for forked repositories._
| GITHUB_REF | GITHUB_HEAD_REF_SLUG_URL |
| ---------- | ------------------------ |
| refs/heads/main | main |
| refs/heads/feat/new_feature | feat-new-feature |
| refs/heads/New_Awesome_Product | new-awesome-product |
## GITHUB_BASE_REF_SLUG_URL
Slug URL the environment variable **GITHUB_BASE_REF**
The branch of the base repository.
_Only set for forked repositories._
| GITHUB_REF | GITHUB_HEAD_REF_SLUG_URL |
| ---------- | ------------------------ |
| refs/heads/main | main |
| refs/heads/feat/new_feature | feat-new-feature |
| refs/heads/New_Awesome_Product | new-awesome-product |
## GITHUB_EVENT_REF_SLUG_URL
Slug URL the variable **github.event.ref**
The Git reference resource associated to triggered webhook.
_Only set for [`create`, and `delete`][1] events._
| GITHUB_REF | GITHUB_HEAD_REF_SLUG_URL |
| ---------- | ------------------------ |
| refs/heads/main | main |
| refs/heads/feat/new_feature | feat-new-feature |
| refs/heads/New_Awesome_Product | new-awesome-product |
[1]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads
This page has moved to [reference/variables.md](reference/variables.md#url-safe-slug-variables).

121
docs/slug-variables.md
View File

@@ -1,122 +1,3 @@
# Slug Variables
## Table of Contents
- [Slug Variables](#slug-variables)
- [Table of Contents](#table-of-contents)
- [GITHUB\_REPOSITORY\_SLUG](#github_repository_slug)
- [GITHUB\_REPOSITORY\_OWNER\_PART\_SLUG](#github_repository_owner_part_slug)
- [GITHUB\_REPOSITORY\_NAME\_PART\_SLUG](#github_repository_name_part_slug)
- [GITHUB\_REF\_SLUG](#github_ref_slug)
- [GITHUB\_REF\_NAME\_SLUG](#github_ref_name_slug)
- [GITHUB\_HEAD\_REF\_SLUG](#github_head_ref_slug)
- [GITHUB\_BASE\_REF\_SLUG](#github_base_ref_slug)
- [GITHUB\_EVENT\_REF\_SLUG](#github_event_ref_slug)
## GITHUB_REPOSITORY_SLUG
Slug the environment variable **GITHUB_REPOSITORY**
The owner and repository name.
| GITHUB_REPOSITORY | GITHUB_REPOSITORY_SLUG |
| ----------------- | ---------------------- |
| octocat/Hello-World | octocat-hello-world |
| rlespinasse/Hello-World.go | rlespinasse-hello-world.go |
| AnotherPerson/SomeRepository | anotherperson-somerepository |
## GITHUB_REPOSITORY_OWNER_PART_SLUG
Slug the environment variable [GITHUB_REPOSITORY_OWNER_PART](partial-variables.md#github_repository_owner_part)
The Owner part of **GITHUB_REPOSITORY** variable.
| GITHUB_REPOSITORY_OWNER_PART | GITHUB_REPOSITORY_OWNER_PART_SLUG |
| ---------------------------- | --------------------------------- |
| octocat | octocat |
| rlespinasse | rlespinasse |
| AnotherPerson | anotherperson |
## GITHUB_REPOSITORY_NAME_PART_SLUG
Slug the environment variable [GITHUB_REPOSITORY_NAME_PART](partial-variables.md#github_repository_name_part)
The Repository name part of **GITHUB_REPOSITORY** variable.
| GITHUB_REPOSITORY_NAME_PART | GITHUB_REPOSITORY_NAME_PART_SLUG |
| --------------------------- | -------------------------------- |
| Hello-World | hello-world |
| Hello-World.go | hello-world.go |
| SomeRepository | somerepository |
## GITHUB_REF_SLUG
Slug the environment variable **GITHUB_REF**
The branch or tag ref that triggered the workflow.
_If neither a branch or tag is available for the event type, the variable will not exist._
| GITHUB_REF | GITHUB_REF_SLUG |
| ---------- | --------------- |
| refs/heads/main | main |
| refs/heads/feat/new_feature | feat-new-feature |
| refs/tags/v1.0.0 | v1.0.0 |
| refs/tags/product@1.0.0-rc.2 | product-1.0.0-rc.2 |
| refs/heads/New_Awesome_Product | new-awesome-product |
## GITHUB_REF_NAME_SLUG
Slug the environment variable **GITHUB_REF_NAME**
The branch or tag ref that triggered the workflow.
_If neither a branch or tag is available for the event type, the variable will not exist._
| GITHUB_REF_NAME | GITHUB_REF_SLUG |
| --------------- | --------------- |
| main | main |
| feat/new_feature | feat-new-feature |
| v1.0.0 | v1.0.0 |
| product@1.0.0-rc.2 | product-1.0.0-rc.2 |
| New_Awesome_Product | new-awesome-product |
| 42/merge | 42-merge |
## GITHUB_HEAD_REF_SLUG
Slug the environment variable **GITHUB_HEAD_REF**
The branch of the head repository.
_Only set for [`pull-request`][1] event and forked repositories._
| GITHUB_REF | GITHUB_HEAD_REF_SLUG |
| ---------- | -------------------- |
| refs/heads/main | main |
| refs/heads/feat/new_feature | feat-new-feature |
| refs/heads/New_Awesome_Product | new-awesome-product |
## GITHUB_BASE_REF_SLUG
Slug the environment variable **GITHUB_BASE_REF**
The branch of the base repository.
_Only set for [`pull-request`][1] event and forked repositories._
| GITHUB_REF | GITHUB_HEAD_REF_SLUG |
| ---------- | -------------------- |
| refs/heads/main | main |
| refs/heads/feat/new_feature | feat-new-feature |
| refs/heads/New_Awesome_Product | new-awesome-product |
## GITHUB_EVENT_REF_SLUG
Slug the variable **github.event.ref**
The Git reference resource associated to triggered webhook.
_Only set for [`create`, and `delete`][1] events._
| GITHUB_REF | GITHUB_HEAD_REF_SLUG |
| ---------- | -------------------- |
| refs/heads/main | main |
| refs/heads/feat/new_feature | feat-new-feature |
| refs/heads/New_Awesome_Product | new-awesome-product |
[1]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads
This page has moved to [reference/variables.md](reference/variables.md#slug-variables).

2
examples/linux-usage.yml
View File

@@ -6,7 +6,7 @@ jobs:
usage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@v6
- uses: rlespinasse/github-slug-action@v5
- name: Output
run: |

2
examples/macos-usage.yml
View File

@@ -6,7 +6,7 @@ jobs:
usage:
runs-on: macos-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@v6
- uses: rlespinasse/github-slug-action@v5
- name: Output
run: |

4
examples/url-use.yml
View File

@@ -6,7 +6,7 @@ jobs:
as_subdomain:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@v6
- uses: rlespinasse/github-slug-action@v5
- run: |
./deploy-application.sh --url "https://${{ env.GITHUB_REF_SLUG_URL }}.staging.app.example.com"
@@ -14,7 +14,7 @@ jobs:
as_resource_path:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@v6
- uses: rlespinasse/github-slug-action@v5
- run: |
./deploy-application.sh --url "https://staging.app.example.com/${{ env.GITHUB_REF_SLUG_URL }}"

2
examples/windows-usage.yml
View File

@@ -6,7 +6,7 @@ jobs:
usage:
runs-on: windows-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@v6
- uses: rlespinasse/github-slug-action@v5
- name: Output
run: |