rlespinasse/github-slug-action
1
0
Fork 0
mirror of https://github.com/rlespinasse/github-slug-action.git synced 2026-06-13 18:11:17 +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

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/