From ef035f61a921ed1ded3607f628ad892e83ce42f9 Mon Sep 17 00:00:00 2001 From: Romain Lespinasse Date: Thu, 12 Mar 2026 14:02:09 +0100 Subject: [PATCH] docs: Reorganize documentation with new reference and explanation sections (#176) Co-authored-by: Claude --- .codespellrc | 2 + README.md | 264 +++------------ docs/explanation/slug-transformation-rules.md | 89 +++++ docs/getting-started.md | 101 ++++++ docs/github-variables.md | 96 +----- docs/how-to/configure-short-length.md | 45 +++ docs/how-to/configure-slug-maxlength.md | 33 ++ docs/how-to/migrate-v3-to-v4.md | 30 ++ docs/how-to/migrate-v4-to-v5.md | 30 ++ docs/how-to/troubleshooting.md | 56 ++++ docs/how-to/use-prefix.md | 26 ++ docs/how-to/use-slugs-in-urls.md | 36 ++ docs/partial-variables.md | 27 +- docs/reference/github-variables.md | 87 +++++ docs/reference/inputs.md | 23 ++ docs/reference/variables.md | 312 ++++++++++++++++++ docs/short-variables.md | 26 +- docs/slug-url-variables.md | 122 +------ docs/slug-variables.md | 121 +------ examples/linux-usage.yml | 2 +- examples/macos-usage.yml | 2 +- examples/url-use.yml | 4 +- examples/windows-usage.yml | 2 +- 23 files changed, 934 insertions(+), 602 deletions(-) create mode 100644 .codespellrc create mode 100644 docs/explanation/slug-transformation-rules.md create mode 100644 docs/getting-started.md create mode 100644 docs/how-to/configure-short-length.md create mode 100644 docs/how-to/configure-slug-maxlength.md create mode 100644 docs/how-to/migrate-v3-to-v4.md create mode 100644 docs/how-to/migrate-v4-to-v5.md create mode 100644 docs/how-to/troubleshooting.md create mode 100644 docs/how-to/use-prefix.md create mode 100644 docs/how-to/use-slugs-in-urls.md create mode 100644 docs/reference/github-variables.md create mode 100644 docs/reference/inputs.md create mode 100644 docs/reference/variables.md diff --git a/.codespellrc b/.codespellrc new file mode 100644 index 0000000..5157d04 --- /dev/null +++ b/.codespellrc @@ -0,0 +1,2 @@ +[codespell] +ignore-words-list = ans diff --git a/README.md b/README.md index b42e771..fc0edea 100644 --- a/README.md +++ b/README.md @@ -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 -- `_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` -- `_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 `/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/ diff --git a/docs/explanation/slug-transformation-rules.md b/docs/explanation/slug-transformation-rules.md new file mode 100644 index 0000000..3651d9c --- /dev/null +++ b/docs/explanation/slug-transformation-rules.md @@ -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 diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..8ff11dd --- /dev/null +++ b/docs/getting-started.md @@ -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 diff --git a/docs/github-variables.md b/docs/github-variables.md index 404af1a..4637516 100644 --- a/docs/github-variables.md +++ b/docs/github-variables.md @@ -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). diff --git a/docs/how-to/configure-short-length.md b/docs/how-to/configure-short-length.md new file mode 100644 index 0000000..62ec09f --- /dev/null +++ b/docs/how-to/configure-short-length.md @@ -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 diff --git a/docs/how-to/configure-slug-maxlength.md b/docs/how-to/configure-slug-maxlength.md new file mode 100644 index 0000000..7d3106e --- /dev/null +++ b/docs/how-to/configure-slug-maxlength.md @@ -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 diff --git a/docs/how-to/migrate-v3-to-v4.md b/docs/how-to/migrate-v3-to-v4.md new file mode 100644 index 0000000..b5b8459 --- /dev/null +++ b/docs/how-to/migrate-v3-to-v4.md @@ -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 diff --git a/docs/how-to/migrate-v4-to-v5.md b/docs/how-to/migrate-v4-to-v5.md new file mode 100644 index 0000000..e1979b2 --- /dev/null +++ b/docs/how-to/migrate-v4-to-v5.md @@ -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 `/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 diff --git a/docs/how-to/troubleshooting.md b/docs/how-to/troubleshooting.md new file mode 100644 index 0000000..04e5b27 --- /dev/null +++ b/docs/how-to/troubleshooting.md @@ -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 diff --git a/docs/how-to/use-prefix.md b/docs/how-to/use-prefix.md new file mode 100644 index 0000000..0a43cf2 --- /dev/null +++ b/docs/how-to/use-prefix.md @@ -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 diff --git a/docs/how-to/use-slugs-in-urls.md b/docs/how-to/use-slugs-in-urls.md new file mode 100644 index 0000000..f3dd8f0 --- /dev/null +++ b/docs/how-to/use-slugs-in-urls.md @@ -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 diff --git a/docs/partial-variables.md b/docs/partial-variables.md index 931c60f..ab4401a 100644 --- a/docs/partial-variables.md +++ b/docs/partial-variables.md @@ -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). diff --git a/docs/reference/github-variables.md b/docs/reference/github-variables.md new file mode 100644 index 0000000..6487fb8 --- /dev/null +++ b/docs/reference/github-variables.md @@ -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 diff --git a/docs/reference/inputs.md b/docs/reference/inputs.md new file mode 100644 index 0000000..b567c9a --- /dev/null +++ b/docs/reference/inputs.md @@ -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 diff --git a/docs/reference/variables.md b/docs/reference/variables.md new file mode 100644 index 0000000..e18918f --- /dev/null +++ b/docs/reference/variables.md @@ -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 `/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 diff --git a/docs/short-variables.md b/docs/short-variables.md index 2c61a28..7e3ffd5 100644 --- a/docs/short-variables.md +++ b/docs/short-variables.md @@ -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). diff --git a/docs/slug-url-variables.md b/docs/slug-url-variables.md index efacb5b..7766654 100644 --- a/docs/slug-url-variables.md +++ b/docs/slug-url-variables.md @@ -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). diff --git a/docs/slug-variables.md b/docs/slug-variables.md index 7079b83..c8b9a6d 100644 --- a/docs/slug-variables.md +++ b/docs/slug-variables.md @@ -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). diff --git a/examples/linux-usage.yml b/examples/linux-usage.yml index 60d0ede..c004438 100644 --- a/examples/linux-usage.yml +++ b/examples/linux-usage.yml @@ -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: | diff --git a/examples/macos-usage.yml b/examples/macos-usage.yml index 2b7c4f1..9d56ebb 100644 --- a/examples/macos-usage.yml +++ b/examples/macos-usage.yml @@ -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: | diff --git a/examples/url-use.yml b/examples/url-use.yml index 084bc0a..670304c 100644 --- a/examples/url-use.yml +++ b/examples/url-use.yml @@ -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 }}" diff --git a/examples/windows-usage.yml b/examples/windows-usage.yml index c299153..0fbf3b4 100644 --- a/examples/windows-usage.yml +++ b/examples/windows-usage.yml @@ -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: |