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