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

Co-authored-by: Claude <noreply@anthropic.com>
2026-06-13 01:51:09 +00:00 · 2026-03-12 14:02:09 +01:00
parent 9e7def6155
commit ef035f61a9
23 changed files with 934 additions and 602 deletions
--- a/docs/reference/github-variables.md
+++ 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
--- a/docs/reference/inputs.md
+++ 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
--- a/docs/reference/variables.md
+++ 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 `<PR#>/merge`, while `GITHUB_REF_POINT` contains the actual branch name.
+
+Available with all slug suffixes: `GITHUB_REF_POINT_SLUG`, `GITHUB_REF_POINT_SLUG_URL`, `GITHUB_REF_POINT_SLUG_CS`, `GITHUB_REF_POINT_SLUG_URL_CS`.
+
+---
+
+## Partial Variables
+
+### GITHUB_REPOSITORY_OWNER_PART
+
+Owner part of the environment variable **GITHUB_REPOSITORY**.
+
+| GITHUB_REPOSITORY | GITHUB_REPOSITORY_OWNER_PART |
+| ----------------- | ---------------------------- |
+| octocat/Hello-World | octocat |
+| rlespinasse/Hello-World.go | rlespinasse |
+| AnotherPerson/SomeRepository | AnotherPerson |
+
+### GITHUB_REPOSITORY_NAME_PART
+
+Repository name part of the environment variable **GITHUB_REPOSITORY**.
+
+| GITHUB_REPOSITORY | GITHUB_REPOSITORY_NAME_PART |
+| ----------------- | --------------------------- |
+| octocat/Hello-World | Hello-World |
+| rlespinasse/Hello-World.go | Hello-World.go |
+| AnotherPerson/SomeRepository | SomeRepository |
+
+---
+
+## Slug Variables
+
+Slug variables apply the [SLUG transformation](../explanation/slug-transformation-rules.md#slug-transformation): lowercase, replace special characters with `-`, preserve `.` and `_`, truncate to max length.
+
+### GITHUB_REPOSITORY_SLUG
+
+Slug of **GITHUB_REPOSITORY** -- the owner and repository name.
+
+| GITHUB_REPOSITORY | GITHUB_REPOSITORY_SLUG |
+| ----------------- | ---------------------- |
+| octocat/Hello-World | octocat-hello-world |
+| rlespinasse/Hello-World.go | rlespinasse-hello-world.go |
+| AnotherPerson/SomeRepository | anotherperson-somerepository |
+
+### GITHUB_REPOSITORY_OWNER_PART_SLUG
+
+Slug of **GITHUB_REPOSITORY_OWNER_PART** -- the owner name.
+
+| GITHUB_REPOSITORY_OWNER_PART | GITHUB_REPOSITORY_OWNER_PART_SLUG |
+| ---------------------------- | --------------------------------- |
+| octocat | octocat |
+| rlespinasse | rlespinasse |
+| AnotherPerson | anotherperson |
+
+### GITHUB_REPOSITORY_NAME_PART_SLUG
+
+Slug of **GITHUB_REPOSITORY_NAME_PART** -- the repository name.
+
+| GITHUB_REPOSITORY_NAME_PART | GITHUB_REPOSITORY_NAME_PART_SLUG |
+| --------------------------- | -------------------------------- |
+| Hello-World | hello-world |
+| Hello-World.go | hello-world.go |
+| SomeRepository | somerepository |
+
+### GITHUB_REF_SLUG
+
+Slug of **GITHUB_REF** -- the branch or tag ref that triggered the workflow.
+_If neither a branch or tag is available for the event type, the variable will not exist._
+
+| GITHUB_REF | GITHUB_REF_SLUG |
+| ---------- | --------------- |
+| refs/heads/main | main |
+| refs/heads/feat/new_feature | feat-new-feature |
+| refs/tags/v1.0.0 | v1.0.0 |
+| refs/tags/product@1.0.0-rc.2 | product-1.0.0-rc.2 |
+| refs/heads/New_Awesome_Product | new-awesome-product |
+
+### GITHUB_REF_NAME_SLUG
+
+Slug of **GITHUB_REF_NAME** -- the branch or tag name shown on GitHub.
+_If neither a branch or tag is available for the event type, the variable will not exist._
+
+| GITHUB_REF_NAME | GITHUB_REF_NAME_SLUG |
+| --------------- | -------------------- |
+| main | main |
+| feat/new_feature | feat-new-feature |
+| v1.0.0 | v1.0.0 |
+| product@1.0.0-rc.2 | product-1.0.0-rc.2 |
+| New_Awesome_Product | new-awesome-product |
+| 42/merge | 42-merge |
+
+### GITHUB_HEAD_REF_SLUG
+
+Slug of **GITHUB_HEAD_REF** -- the branch of the head repository.
+_Only set for [`pull_request*`][webhooks] events and forked repositories._
+
+| GITHUB_HEAD_REF | GITHUB_HEAD_REF_SLUG |
+| --------------- | -------------------- |
+| main | main |
+| feat/new_feature | feat-new-feature |
+| New_Awesome_Product | new-awesome-product |
+
+### GITHUB_BASE_REF_SLUG
+
+Slug of **GITHUB_BASE_REF** -- the branch of the base repository.
+_Only set for [`pull_request*`][webhooks] events and forked repositories._
+
+| GITHUB_BASE_REF | GITHUB_BASE_REF_SLUG |
+| --------------- | -------------------- |
+| main | main |
+| feat/new_feature | feat-new-feature |
+| New_Awesome_Product | new-awesome-product |
+
+### GITHUB_EVENT_REF_SLUG
+
+Slug of **github.event.ref** -- the Git reference resource associated to the triggered webhook.
+_Only set for [`create` and `delete`][webhooks] events._
+
+| github.event.ref | GITHUB_EVENT_REF_SLUG |
+| ---------------- | --------------------- |
+| main | main |
+| feat/new_feature | feat-new-feature |
+| New_Awesome_Product | new-awesome-product |
+
+---
+
+## URL-Safe Slug Variables
+
+URL-safe slug variables apply the [SLUG_URL transformation](../explanation/slug-transformation-rules.md#slug_url-transformation): same as SLUG but `.` and `_` are also replaced with `-`.
+
+### GITHUB_REPOSITORY_SLUG_URL
+
+URL-safe slug of **GITHUB_REPOSITORY** -- the owner and repository name.
+
+| GITHUB_REPOSITORY | GITHUB_REPOSITORY_SLUG_URL |
+| ----------------- | -------------------------- |
+| octocat/Hello-World | octocat-hello-world |
+| rlespinasse/Hello-World.go | rlespinasse-hello-world-go |
+| AnotherPerson/SomeRepository | anotherperson-somerepository |
+
+### GITHUB_REPOSITORY_OWNER_PART_SLUG_URL
+
+URL-safe slug of **GITHUB_REPOSITORY_OWNER_PART** -- the owner name.
+
+| GITHUB_REPOSITORY_OWNER_PART | GITHUB_REPOSITORY_OWNER_PART_SLUG_URL |
+| ---------------------------- | ------------------------------------- |
+| octocat | octocat |
+| rlespinasse | rlespinasse |
+| AnotherPerson | anotherperson |
+
+### GITHUB_REPOSITORY_NAME_PART_SLUG_URL
+
+URL-safe slug of **GITHUB_REPOSITORY_NAME_PART** -- the repository name.
+
+| GITHUB_REPOSITORY_NAME_PART | GITHUB_REPOSITORY_NAME_PART_SLUG_URL |
+| --------------------------- | ------------------------------------ |
+| Hello-World | hello-world |
+| Hello-World.go | hello-world-go |
+| SomeRepository | somerepository |
+
+### GITHUB_REF_SLUG_URL
+
+URL-safe slug of **GITHUB_REF** -- the branch or tag ref that triggered the workflow.
+_If neither a branch or tag is available for the event type, the variable will not exist._
+
+| GITHUB_REF | GITHUB_REF_SLUG_URL |
+| ---------- | ------------------- |
+| refs/heads/main | main |
+| refs/heads/feat/new_feature | feat-new-feature |
+| refs/tags/v1.0.0 | v1-0-0 |
+| refs/pull/42/merge | 42-merge |
+| refs/tags/product@1.0.0-rc.2 | product-1-0-0-rc-2 |
+| refs/heads/New_Awesome_Product | new-awesome-product |
+
+### GITHUB_REF_NAME_SLUG_URL
+
+URL-safe slug of **GITHUB_REF_NAME** -- the branch or tag name shown on GitHub.
+_If neither a branch or tag is available for the event type, the variable will not exist._
+
+| GITHUB_REF_NAME | GITHUB_REF_NAME_SLUG_URL |
+| --------------- | ------------------------ |
+| main | main |
+| feat/new_feature | feat-new-feature |
+| v1.0.0 | v1-0-0 |
+| 42/merge | 42-merge |
+| product@1.0.0-rc.2 | product-1-0-0-rc-2 |
+| New_Awesome_Product | new-awesome-product |
+
+### GITHUB_HEAD_REF_SLUG_URL
+
+URL-safe slug of **GITHUB_HEAD_REF** -- the branch of the head repository.
+_Only set for [`pull_request*`][webhooks] events and forked repositories._
+
+| GITHUB_HEAD_REF | GITHUB_HEAD_REF_SLUG_URL |
+| --------------- | ------------------------ |
+| main | main |
+| feat/new_feature | feat-new-feature |
+| New_Awesome_Product | new-awesome-product |
+
+### GITHUB_BASE_REF_SLUG_URL
+
+URL-safe slug of **GITHUB_BASE_REF** -- the branch of the base repository.
+_Only set for [`pull_request*`][webhooks] events and forked repositories._
+
+| GITHUB_BASE_REF | GITHUB_BASE_REF_SLUG_URL |
+| --------------- | ------------------------ |
+| main | main |
+| feat/new_feature | feat-new-feature |
+| New_Awesome_Product | new-awesome-product |
+
+### GITHUB_EVENT_REF_SLUG_URL
+
+URL-safe slug of **github.event.ref** -- the Git reference resource associated to the triggered webhook.
+_Only set for [`create` and `delete`][webhooks] events._
+
+| github.event.ref | GITHUB_EVENT_REF_SLUG_URL |
+| ---------------- | ------------------------- |
+| main | main |
+| feat/new_feature | feat-new-feature |
+| New_Awesome_Product | new-awesome-product |
+
+---
+
+## Short Variables
+
+### GITHUB_SHA_SHORT
+
+Shortened **GITHUB_SHA** -- the commit SHA that triggered the workflow.
+
+| GITHUB_SHA | GITHUB_SHA_SHORT |
+| ---------- | ---------------- |
+| ffac537e6cbbf934b08745a378932722df287a53 | ffac537e |
+
+### GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT
+
+Shortened value of `github.event.pull_request.head.sha` -- the last commit on the pull request that triggered the workflow.
+
+| github.event.pull_request.head.sha | GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT |
+| ---------------------------------- | ---------------------------------------- |
+| ffac537e6cbbf934b08745a378932722df287a53 | ffac537e |
+
+---
+
+## Case-Sensitive Variants
+
+All slug and slug-url variables have a `_CS` suffix variant that preserves the original casing. The `_CS` variant applies the same transformation but skips the lowercase step.
+
+| Standard | Case-Sensitive |
+| -------- | -------------- |
+| `GITHUB_REPOSITORY_SLUG` | `GITHUB_REPOSITORY_SLUG_CS` |
+| `GITHUB_REPOSITORY_SLUG_URL` | `GITHUB_REPOSITORY_SLUG_URL_CS` |
+| `GITHUB_REF_SLUG` | `GITHUB_REF_SLUG_CS` |
+| `GITHUB_REF_SLUG_URL` | `GITHUB_REF_SLUG_URL_CS` |
+| _(and so on for all slug/slug-url variables)_ | |
+
+Example:
+
+| Input | SLUG | SLUG_CS |
+| ----- | ---- | ------- |
+| `refs/heads/New_Awesome_Product` | `new-awesome-product` | `New-Awesome-Product` |
+
+---
+
+## Variable Availability by Event
+
+Not all variables are set for every event type. See [GitHub variables by event](github-variables.md) for the full matrix.
+
+[webhooks]: https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads