Skip to content

Commit ef035f6

Browse files
rlespinasseclaude
rlespinasse
and
claude
authored
docs: Reorganize documentation with new reference and explanation sections (#176)
Co-authored-by: Claude <noreply@anthropic.com>
1 parent 9e7def6 commit ef035f6

23 files changed

+933
-601
lines changed

‎.codespellrc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
[codespell]
2+
ignore-words-list = ans

‎README.md‎

Lines changed: 53 additions & 209 deletions
Large diffs are not rendered by default.

‎docs/explanation/slug-transformation-rules.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Slug Transformation Rules
2+
3+
This page explains the transformation algorithms used by the GitHub Slug Action, why they exist, and how they differ from each other.
4+
5+
## What is a "slug"?
6+
7+
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.
8+
9+
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.
10+
11+
## SLUG transformation
12+
13+
The `SLUG` transformation applies the following steps in order:
14+
15+
1. **Lowercase** the entire string
16+
2. **Replace** any character that is not `0-9`, `a-z`, `.`, or `_` with `-`
17+
3. **Remove** leading `-` characters
18+
4. **Truncate** to a maximum length (default: 63 characters)
19+
5. **Remove** trailing `-` characters
20+
21+
### SLUG examples
22+
23+
| Input | Output |
24+
| ----- | ------ |
25+
| `refs/heads/feat/new_feature` | `feat-new-feature` |
26+
| `refs/tags/v1.0.0` | `v1.0.0` |
27+
| `refs/tags/product@1.0.0-rc.2` | `product-1.0.0-rc.2` |
28+
| `octocat/Hello-World` | `octocat-hello-world` |
29+
30+
Note that `.` and `_` are preserved in SLUG output.
31+
32+
## SLUG_URL transformation
33+
34+
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.
35+
36+
### SLUG_URL examples
37+
38+
| Input | SLUG | SLUG_URL |
39+
| ----- | ---- | -------- |
40+
| `refs/tags/v1.0.0` | `v1.0.0` | `v1-0-0` |
41+
| `rlespinasse/Hello-World.go` | `rlespinasse-hello-world.go` | `rlespinasse-hello-world-go` |
42+
| `refs/heads/feat/new_feature` | `feat-new-feature` | `feat-new-feature` |
43+
44+
### When to use which
45+
46+
- Use **SLUG** for Docker tags, file paths, and general identifiers (dots and underscores are allowed)
47+
- Use **SLUG_URL** for subdomains, URL path segments, and any context where dots or underscores are problematic
48+
49+
## Why 63 characters?
50+
51+
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:
52+
53+
- Kubernetes resource labels
54+
- Many cloud provider resource names
55+
- DNS subdomain components
56+
57+
You can change this limit with the `slug-maxlength` input, or set it to `"nolimit"` to disable truncation entirely.
58+
59+
## SHORT transformation
60+
61+
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].
62+
63+
| Input | Output |
64+
| ----- | ------ |
65+
| `ffac537e6cbbf934b08745a378932722df287a53` | `ffac537e` |
66+
67+
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).
68+
69+
## Case-sensitive variants (_CS)
70+
71+
Every `SLUG` and `SLUG_URL` variable also has a `_CS` (case-sensitive) variant that skips the lowercase step. For example:
72+
73+
| Input | SLUG | SLUG_CS |
74+
| ----- | ---- | ------- |
75+
| `refs/heads/New_Awesome_Product` | `new-awesome-product` | `New-Awesome-Product` |
76+
77+
This is useful when the original casing carries meaning (e.g., product names).
78+
79+
## PART extraction
80+
81+
The `PART` transformation splits a composite value and extracts a portion. Currently used for `GITHUB_REPOSITORY`:
82+
83+
| Input | OWNER_PART | NAME_PART |
84+
| ----- | ---------- | --------- |
85+
| `octocat/Hello-World` | `octocat` | `Hello-World` |
86+
87+
PART variables preserve the original casing. They can be further transformed using SLUG or SLUG_URL suffixes (e.g., `GITHUB_REPOSITORY_OWNER_PART_SLUG`).
88+
89+
[git-revparse]: https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt---shortlength

‎docs/getting-started.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Getting Started with GitHub Slug Action
2+
3+
This tutorial walks you through adding the GitHub Slug Action to a workflow and using slug variables for the first time.
4+
5+
## Prerequisites
6+
7+
- A GitHub repository with [GitHub Actions enabled](https://docs.github.com/en/actions/using-workflows)
8+
9+
## Step 1: Add the action to your workflow
10+
11+
Create or edit a workflow file (e.g., `.github/workflows/deploy.yml`) and add the action after checking out your code:
12+
13+
```yaml
14+
name: Deploy
15+
16+
on: push
17+
18+
jobs:
19+
deploy:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v6
23+
24+
- name: Inject enhanced GitHub environment variables
25+
uses: rlespinasse/github-slug-action@v5
26+
```
27+
28+
> [!TIP]
29+
> 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.
30+
31+
## Step 2: Use slug variables in subsequent steps
32+
33+
After the action runs, all slug variables are available as environment variables. Add a step to use them:
34+
35+
```yaml
36+
- name: Print slug variables
37+
run: |
38+
echo "Repository slug: $GITHUB_REPOSITORY_SLUG"
39+
echo "Branch slug: $GITHUB_REF_SLUG"
40+
echo "Short SHA: $GITHUB_SHA_SHORT"
41+
shell: bash
42+
```
43+
44+
For a branch named `feat/new_feature` on repository `octocat/Hello-World`, this outputs:
45+
46+
```text
47+
Repository slug: octocat-hello-world
48+
Branch slug: feat-new-feature
49+
Short SHA: ffac537e
50+
```
51+
52+
## Step 3: Use a slug variable for a practical purpose
53+
54+
A common use case is naming deployment previews with a URL-safe branch identifier:
55+
56+
```yaml
57+
- name: Deploy preview
58+
run: |
59+
echo "Deploying to https://${GITHUB_REF_SLUG_URL}.preview.example.com"
60+
shell: bash
61+
```
62+
63+
The `SLUG_URL` variant replaces dots and underscores too, making it safe for subdomains.
64+
65+
## Complete workflow
66+
67+
Here is the full workflow file:
68+
69+
```yaml
70+
name: Deploy
71+
72+
on: push
73+
74+
jobs:
75+
deploy:
76+
runs-on: ubuntu-latest
77+
steps:
78+
- uses: actions/checkout@v6
79+
80+
- name: Inject enhanced GitHub environment variables
81+
uses: rlespinasse/github-slug-action@v5
82+
83+
- name: Deploy preview
84+
run: |
85+
echo "Deploying to https://${GITHUB_REF_SLUG_URL}.preview.example.com"
86+
echo "Commit: ${GITHUB_SHA_SHORT}"
87+
shell: bash
88+
```
89+
90+
## What you learned
91+
92+
- **SLUG** variables convert values to lowercase and replace special characters with `-`
93+
- **SLUG_URL** variables also replace `.` and `_`, making values safe for URLs and subdomains
94+
- **SHORT** variables shorten SHA commit hashes
95+
- All variables are exposed as environment variables for use in subsequent steps
96+
97+
## Next steps
98+
99+
- [How-to guides](how-to/) for specific configuration tasks (prefixes, custom lengths, URL usage)
100+
- [Variable reference](reference/variables.md) for the complete list of available variables
101+
- [Slug transformation rules](explanation/slug-transformation-rules.md) to understand how transformations work

‎docs/github-variables.md‎

Lines changed: 1 addition & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,3 @@
11
# Available GitHub Variables
22

3-
All `GitHub` variables availables in your workflow in addition of ones exposed by this Action
4-
5-
## Table of Contents
6-
7-
- [Available GitHub Variables](#available-github-variables)
8-
- [Table of Contents](#table-of-contents)
9-
- [Default environment variables](#default-environment-variables)
10-
- [Action-managed Environment Variables](#action-managed-environment-variables)
11-
- [Variables from events](#variables-from-events)
12-
- [Action-managed Event Variables](#action-managed-event-variables)
13-
- [create](#create)
14-
- [delete](#delete)
15-
- [pull\_request](#pull_request)
16-
- [pull\_request\_review](#pull_request_review)
17-
- [pull\_request\_review\_comment](#pull_request_review_comment)
18-
- [pull\_request\_target](#pull_request_target)
19-
20-
## Default environment variables
21-
22-
Read the official documentation about [Default environment variables][1].
23-
24-
### Action-managed Environment Variables
25-
26-
| Action-managed Variables | Can be suffix by |
27-
| ------------------------ | --------------- |
28-
| GITHUB_REPOSITORY | `_SLUG`, `_SLUG_URL` |
29-
| GITHUB_REF | `_SLUG`, `_SLUG_URL` |
30-
| GITHUB_REF_NAME | `_SLUG`, `_SLUG_URL` |
31-
| GITHUB_HEAD_REF | `_SLUG`, `_SLUG_URL` |
32-
| GITHUB_BASE_REF | `_SLUG`, `_SLUG_URL` |
33-
| GITHUB_SHA | `_SHORT` |
34-
35-
## Variables from events
36-
37-
Read the official documentation about [Events that trigger workflows][2].
38-
39-
### Action-managed Event Variables
40-
41-
#### create
42-
43-
Checkout [create][3] webhook payload content
44-
45-
| Action-managed Variables | Available as |
46-
| ------------------------ | ------------ |
47-
| github.event.ref | GITHUB_EVENT_REF_SLUG |
48-
| github.event.ref | GITHUB_EVENT_REF_SLUG_URL |
49-
50-
#### delete
51-
52-
Checkout [delete][4] webhook payload content
53-
54-
| Action-managed Variables | Available as |
55-
| ------------------------ | ------------ |
56-
| github.event.ref | GITHUB_EVENT_REF_SLUG |
57-
| github.event.ref | GITHUB_EVENT_REF_SLUG_URL |
58-
59-
#### pull_request
60-
61-
Checkout [pull_request][5] webhook payload content
62-
63-
| Action-managed Variables | Available as |
64-
| ------------------------ | ------------ |
65-
| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
66-
67-
#### pull_request_review
68-
69-
Checkout [pull_request_review][6] webhook payload content
70-
71-
| Action-managed Variables | Available as |
72-
| ------------------------ | ------------ |
73-
| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
74-
75-
#### pull_request_review_comment
76-
77-
Checkout [pull_request_review_comment][7] webhook payload content
78-
79-
| Action-managed Variables | Available as |
80-
| ------------------------ | ------------ |
81-
| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
82-
83-
#### pull_request_target
84-
85-
Checkout [pull_request][5] webhook payload content
86-
87-
| Action-managed Variables | Available as |
88-
| ------------------------ | ------------ |
89-
| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
90-
91-
[1]: https://docs.github.com/en/actions/reference/environment-variables#default-environment-variables
92-
[2]: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
93-
[3]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#create
94-
[4]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#delete
95-
[5]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#pull_request
96-
[6]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#pull_request_review
97-
[7]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#pull_request_review_comment
3+
This page has moved to [reference/github-variables.md](reference/github-variables.md).

‎docs/how-to/configure-short-length.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Configure the length of short SHA values
2+
3+
Set a specific length for shortened commit SHA values instead of letting Git determine it automatically.
4+
5+
## Usage
6+
7+
```yaml
8+
steps:
9+
- name: Inject enhanced GitHub environment variables
10+
uses: rlespinasse/github-slug-action@v5
11+
with:
12+
short-length: 7
13+
```
14+
15+
## Common values
16+
17+
| Value | Use case |
18+
| ----- | -------- |
19+
| _(empty)_ | Let Git decide based on repository size (default) |
20+
| `7` | Common "small repository" length |
21+
| `8` | Reproduce `v3` action behaviour |
22+
| `4` | Minimum allowed length |
23+
24+
## Letting Git decide (default)
25+
26+
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.
27+
28+
> [!WARNING]
29+
> If you leave `short-length` empty, you need to checkout the source first so Git can determine the length:
30+
>
31+
> ```yaml
32+
> steps:
33+
> - uses: actions/checkout@v6
34+
> - uses: rlespinasse/github-slug-action@v5
35+
> ```
36+
>
37+
> 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.
38+
39+
## See also
40+
41+
- [Inputs reference](../reference/inputs.md) for the full specification
42+
- [SHORT transformation](../explanation/slug-transformation-rules.md#short-transformation) for how short values are computed
43+
44+
[git-revparse]: https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt---shortlength
45+
[git-core-abbrev]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreabbrev

‎docs/how-to/configure-slug-maxlength.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Configure the maximum length for slug values
2+
3+
Change the maximum length of slugified values. The default is 63 characters (the DNS label length limit).
4+
5+
## Usage
6+
7+
```yaml
8+
steps:
9+
- name: Inject enhanced GitHub environment variables
10+
uses: rlespinasse/github-slug-action@v5
11+
with:
12+
slug-maxlength: 80
13+
```
14+
15+
## Disable the length limit
16+
17+
Set `slug-maxlength` to `"nolimit"` to disable truncation entirely:
18+
19+
```yaml
20+
steps:
21+
- name: Inject enhanced GitHub environment variables
22+
uses: rlespinasse/github-slug-action@v5
23+
with:
24+
slug-maxlength: nolimit
25+
```
26+
27+
> [!WARNING]
28+
> The `slug-maxlength` input must not be empty. If left empty, the action will fail during preflight validation.
29+
30+
## See also
31+
32+
- [Inputs reference](../reference/inputs.md) for the full specification
33+
- [Why 63 characters?](../explanation/slug-transformation-rules.md#why-63-characters) for the rationale behind the default

0 commit comments

Comments
 (0)