diff --git a/docs/usage/actions/faq.md b/docs/usage/actions/faq.md
index 739154e8..fcf1015c 100644
--- a/docs/usage/actions/faq.md
+++ b/docs/usage/actions/faq.md
@@ -149,22 +149,26 @@ In case you fork Gitea Runner to create your own version: Please contribute the
All events listed in this table are supported events and are compatible with GitHub.
For events supported only by GitHub, see GitHub's [documentation](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows).
-| trigger event | activity types |
-|-----------------------------|--------------------------------------------------------------------------------------------------------------------------|
-| create | not applicable |
-| delete | not applicable |
-| fork | not applicable |
-| gollum | not applicable |
-| push | not applicable |
-| issues | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled` |
-| issue_comment | `created`, `edited`, `deleted` |
-| pull_request | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronized`, `labeled`, `unlabeled` |
-| pull_request_review | `submitted`, `edited` |
-| pull_request_review_comment | `created`, `edited` |
-| release | `published`, `edited` |
-| registry_package | `published` |
-| workflow_dispatch | not applicable |
-| workflow_run | `requested`, `completed` |
+| trigger event | activity types |
+|----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| create | not applicable |
+| delete | not applicable |
+| fork | not applicable |
+| gollum | not applicable |
+| push | not applicable |
+| schedule | not applicable |
+| workflow_dispatch | not applicable |
+| workflow_call | not applicable |
+| issues | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled` |
+| issue_comment | `created`, `edited`, `deleted` |
+| pull_request
pull_request_target | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronize`, `labeled`, `unlabeled`, `milestoned`, `demilestoned`, `review_requested`, `review_request_removed` |
+| pull_request_review | `submitted`, `edited` |
+| pull_request_review_comment | `created`, `edited` |
+| release | `published`, `edited` |
+| registry_package | `published` |
+| workflow_run | `requested`, `in_progress`, `completed` |
+
+> Without an explicit `types:` filter, `pull_request` and `pull_request_target` only run on `opened`, `reopened` and `synchronize`, matching GitHub. All other events run on every activity type they support.
> For `pull_request` events, in [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request), the `ref` is `refs/pull/:prNumber/merge`, which is a reference to the merge commit preview. However, Gitea has no such reference.
> Therefore, the `ref` in Gitea Actions is `refs/pull/:prNumber/head`, which points to the head of pull request rather than the preview of the merge commit.
diff --git a/docs/usage/actions/variables.md b/docs/usage/actions/variables.md
index e288638d..958ed127 100644
--- a/docs/usage/actions/variables.md
+++ b/docs/usage/actions/variables.md
@@ -6,80 +6,10 @@ sidebar_position: 25
# Variables
-## User-defined variables
-
-You can create configuration variables on the user, organization and repository level.
-The level of the variable depends on where you created it. When creating a variable, the
-key will be converted to uppercase. You need use uppercase on the yaml file.
-
-### Naming conventions
-
-The following rules apply to variable names:
-
-- Variable names can only contain alphanumeric characters (`[a-z]`, `[A-Z]`, `[0-9]`) or underscores (`_`). Spaces are not allowed.
-- Variable names must not start with the `GITHUB_` and `GITEA_` prefix.
-- Variable names must not start with a number.
-- Variable names are case-insensitive.
-- Variable names must be unique at the level they are created at.
-- Variable names must not start with `CI`.
-
-### Using variables
-
-After creating configuration variables, they will be automatically filled in the `vars` context.
-They can be accessed through expressions like `${{ vars.VARIABLE_NAME }}` in the workflow.
-
-### Precedence
-
-If a variable with the same name exists at multiple levels, the variable at the lowest level takes precedence:
-A repository variable will always be chosen over an organization/user variable.
-
-## Pre-defined context variables
-
-These variables are available in workflow expressions via `${{ gitea. }}`. For compatibility, `${{ github. }}` works as an alias.
-
-| Name | Description | Example |
-|---|---|---|
-| `gitea.action`
`github.action` | The name of the action currently running, or the `id` of a step. | `__run` |
-| `gitea.action_path`
`github.action_path` | The path where an action is located. Only supported in composite actions. | `/home/runner/work/_actions/actions/checkout/v4` |
-| `gitea.action_ref`
`github.action_ref` | The ref of the action being executed. | `v4` |
-| `gitea.action_repository`
`github.action_repository` | The owner and repository name of the action. | `actions/checkout` |
-| `gitea.action_status`
`github.action_status` | The current result of a composite action. | `success` |
-| `gitea.actor`
`github.actor` | The username of the user that triggered the initial workflow run. | `silverwind` |
-| `gitea.api_url`
`github.api_url` | The URL of the REST API. | `https://gitea.com/api/v1` |
-| `gitea.base_ref`
`github.base_ref` | The target branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `main` |
-| `gitea.env`
`github.env` | Path on the runner to the file that sets environment variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
-| `gitea.event`
`github.event` | The full event webhook payload as an object. | `{...}` |
-| `gitea.event_name`
`github.event_name` | The name of the event that triggered the workflow run. | `push` |
-| `gitea.event_path`
`github.event_path` | Path on the runner to the file containing the full event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
-| `gitea.head_ref`
`github.head_ref` | The source branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `feature-branch` |
-| `gitea.job`
`github.job` | The `job_id` of the current job. | `build` |
-| `gitea.ref`
`github.ref` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
-| `gitea.ref_name`
`github.ref_name` | The short ref name. | `main` |
-| `gitea.ref_protected`
`github.ref_protected` | `true` if branch protections are configured for the ref that triggered the workflow run. | `true` |
-| `gitea.ref_type`
`github.ref_type` | The type of ref: `branch` or `tag`. | `branch` |
-| `gitea.path`
`github.path` | Path on the runner to the file that sets system `PATH` variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
-| `gitea.repository`
`github.repository` | The owner and repository name. | `gitea/docs` |
-| `gitea.repository_owner`
`github.repository_owner` | The repository owner's username. | `gitea` |
-| `gitea.repositoryUrl`
`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.com/gitea/docs` |
-| `gitea.retention_days`
`github.retention_days` | The number of days that workflow run logs and artifacts are kept. | `90` |
-| `gitea.run_id`
`github.run_id` | A unique number for each workflow run within a repository. Does not change on re-run. | `1234` |
-| `gitea.run_number`
`github.run_number` | A unique number for each run of a particular workflow. Starts at 1 and increments with each new run. | `42` |
-| `gitea.run_attempt`
`github.run_attempt` | A unique number for each re-run attempt. Starts at 1 and increments with each re-run. | `1` |
-| `gitea.secret_source`
`github.secret_source` | The source of a secret used in a workflow. Always `Actions` in Gitea. | `Actions` |
-| `gitea.server_url`
`github.server_url` | The URL of the Gitea instance. | `https://gitea.com` |
-| `gitea.sha`
`github.sha` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
-| `gitea.token`
`github.token` | A token to authenticate on behalf of the Gitea App installed on the repository. See [Token permissions](token-permissions.md). | `ghs_***` |
-| `gitea.triggering_actor`
`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `silverwind` |
-| `gitea.workflow`
`github.workflow` | The name of the workflow. If unnamed, the full path of the workflow file. | `CI` |
-| `gitea.workspace`
`github.workspace` | The default working directory on the runner and the default location of your repository when using the `checkout` action. | `/workspace/gitea/docs` |
-| `gitea.gitea_default_actions_url` | The default URL for downloading actions. Gitea-specific. | `https://github.com` |
-
-## Pre-defined environment variables
+## Environment variables
These environment variables are set automatically in every workflow run and can be accessed directly (e.g. `$CI` in shell scripts).
-### Standard environment variables
-
| Name | Description | Example |
|---|---|---|
| `CI` | Always set to `true`. | `true` |
@@ -138,3 +68,124 @@ These are used internally by the runner and actions. They are typically not need
| `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.com` |
| `ACTIONS_RUNTIME_TOKEN` | Authentication token for the Actions pipeline API. | `***` |
| `ACTIONS_RUNTIME_URL` | URL for the Gitea Actions pipeline API. | `https://gitea.com/api/actions_pipeline/` |
+
+## Context variables
+
+These variables are available in workflow expressions via `${{ gitea. }}`. For compatibility, `${{ github. }}` works as an alias.
+
+| Name | Description | Example |
+|---|---|---|
+| `gitea.action`
`github.action` | The name of the action currently running, or the `id` of a step. | `__run` |
+| `gitea.action_path`
`github.action_path` | The path where an action is located. Only supported in composite actions. | `/home/runner/work/_actions/actions/checkout/v4` |
+| `gitea.action_ref`
`github.action_ref` | The ref of the action being executed. | `v4` |
+| `gitea.action_repository`
`github.action_repository` | The owner and repository name of the action. | `actions/checkout` |
+| `gitea.action_status`
`github.action_status` | The current result of a composite action. | `success` |
+| `gitea.actor`
`github.actor` | The username of the user that triggered the initial workflow run. | `silverwind` |
+| `gitea.api_url`
`github.api_url` | The URL of the REST API. | `https://gitea.com/api/v1` |
+| `gitea.base_ref`
`github.base_ref` | The target branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `main` |
+| `gitea.env`
`github.env` | Path on the runner to the file that sets environment variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
+| `gitea.event`
`github.event` | The full event webhook payload as an object. See [Event payload](#event-payload). | `{...}` |
+| `gitea.event_name`
`github.event_name` | The name of the event that triggered the workflow run. | `push` |
+| `gitea.event_path`
`github.event_path` | Path on the runner to the file containing the full event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
+| `gitea.head_ref`
`github.head_ref` | The source branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `feature-branch` |
+| `gitea.job`
`github.job` | The `job_id` of the current job. | `build` |
+| `gitea.ref`
`github.ref` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
+| `gitea.ref_name`
`github.ref_name` | The short ref name. | `main` |
+| `gitea.ref_protected`
`github.ref_protected` | `true` if branch protections are configured for the ref that triggered the workflow run. | `true` |
+| `gitea.ref_type`
`github.ref_type` | The type of ref: `branch` or `tag`. | `branch` |
+| `gitea.path`
`github.path` | Path on the runner to the file that sets system `PATH` variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
+| `gitea.repository`
`github.repository` | The owner and repository name. | `gitea/docs` |
+| `gitea.repository_owner`
`github.repository_owner` | The repository owner's username. | `gitea` |
+| `gitea.repositoryUrl`
`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.com/gitea/docs` |
+| `gitea.retention_days`
`github.retention_days` | The number of days that workflow run logs and artifacts are kept. | `90` |
+| `gitea.run_id`
`github.run_id` | A unique number for each workflow run within a repository. Does not change on re-run. | `1234` |
+| `gitea.run_number`
`github.run_number` | A unique number for each run of a particular workflow. Starts at 1 and increments with each new run. | `42` |
+| `gitea.run_attempt`
`github.run_attempt` | A unique number for each re-run attempt. Starts at 1 and increments with each re-run. | `1` |
+| `gitea.secret_source`
`github.secret_source` | The source of a secret used in a workflow. Always `Actions` in Gitea. | `Actions` |
+| `gitea.server_url`
`github.server_url` | The URL of the Gitea instance. | `https://gitea.com` |
+| `gitea.sha`
`github.sha` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
+| `gitea.token`
`github.token` | A token to authenticate on behalf of the Gitea App installed on the repository. See [Token permissions](token-permissions.md). | `ghs_***` |
+| `gitea.triggering_actor`
`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `silverwind` |
+| `gitea.workflow`
`github.workflow` | The name of the workflow. If unnamed, the full path of the workflow file. | `CI` |
+| `gitea.workspace`
`github.workspace` | The default working directory on the runner and the default location of your repository when using the `checkout` action. | `/workspace/gitea/docs` |
+| `gitea.gitea_default_actions_url` | The default URL for downloading actions. Gitea-specific. | `https://github.com` |
+
+### Event payload
+
+`gitea.event` is the webhook payload of the event that triggered the run, so which fields exist depends on `gitea.event_name`.
+The same payload is written as JSON to the file at `gitea.event_path`.
+
+Payloads use Gitea's webhook format, which is close to GitHub's but not identical. Differences are noted below.
+Reading a field that the payload does not have returns an empty value instead of failing, so `${{ gitea.event.pull_request.number }}` is empty on a `push` run.
+
+These fields exist in almost every payload:
+
+| Name | Description | Example |
+|---|---|---|
+| `gitea.event.action` | The activity type. Only set for events that have activity types, see [supported events](faq.md#what-workflow-trigger-events-does-gitea-support). | `opened` |
+| `gitea.event.repository.full_name` | The owner and name of the repository. | `gitea/docs` |
+| `gitea.event.repository.default_branch` | The default branch of the repository. | `main` |
+| `gitea.event.repository.private` | Whether the repository is private. | `false` |
+| `gitea.event.repository.html_url` | The HTML URL of the repository. | `https://gitea.com/gitea/docs` |
+| `gitea.event.sender.login` | The username of the user that triggered the event. Also available as `sender.username`. | `silverwind` |
+
+The remaining fields are specific to one or a few events:
+
+| Name | Events | Description | Example |
+|---|---|---|---|
+| `gitea.event.schedule` | `schedule` | The cron expression that triggered the run. | `*/5 * * * *` |
+| `gitea.event.inputs.` | `workflow_dispatch`, `workflow_call` | A raw input value. Prefer `${{ inputs. }}`, which also applies the input's `default`. | `true` |
+| `gitea.event.workflow` | `workflow_dispatch` | The file name of the dispatched workflow. | `ci.yaml` |
+| `gitea.event.ref` | `push`, `create`, `delete`, `workflow_dispatch` | The ref of the event. Unlike GitHub, `create` and `delete` use the full ref instead of the short name. | `refs/heads/main` |
+| `gitea.event.ref_type` | `create`, `delete` | The type of ref: `branch` or `tag`. | `tag` |
+| `gitea.event.before`
`gitea.event.after` | `push` | The commit SHA before and after the push. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
+| `gitea.event.commits` | `push` | The commits contained in the push, each with `id`, `message`, `url`, `author`, `added`, `removed` and `modified`. | `[{...}]` |
+| `gitea.event.head_commit.message` | `push` | The message of the most recent commit of the push. | `fix: broken link` |
+| `gitea.event.total_commits` | `push` | The number of commits in the push. Gitea-specific. | `3` |
+| `gitea.event.compare_url` | `push` | The URL comparing `before` with `after`. GitHub names this field `compare`. | `https://gitea.com/gitea/docs/compare/a1b2c3d...e5f6a1b` |
+| `gitea.event.pusher.login` | `push` | The username of the user that pushed. | `silverwind` |
+| `gitea.event.forkee.full_name` | `fork` | The owner and name of the new fork. | `silverwind/docs` |
+| `gitea.event.page` | `gollum` | The name of the wiki page. | `Home` |
+| `gitea.event.number` | `issues`, `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The index of the issue or pull request. Not set for `issue_comment`, use `gitea.event.issue.number` there. | `386` |
+| `gitea.event.issue.number`
`gitea.event.issue.title`
`gitea.event.issue.body`
`gitea.event.issue.state`
`gitea.event.issue.labels`
`gitea.event.issue.user.login` | `issues`, `issue_comment` | The issue the event happened on. | `Expand gitea.event in actions docs` |
+| `gitea.event.comment.body` | `issue_comment` | The body of the comment. | `LGTM` |
+| `gitea.event.is_pull` | `issue_comment` | Whether the comment was made on a pull request. Gitea-specific, GitHub sets `issue.pull_request` on the issue object instead. | `true` |
+| `gitea.event.pull_request.number`
`gitea.event.pull_request.title`
`gitea.event.pull_request.body`
`gitea.event.pull_request.draft`
`gitea.event.pull_request.merged`
`gitea.event.pull_request.state`
`gitea.event.pull_request.labels`
`gitea.event.pull_request.user.login` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The pull request the event happened on. | `Add caching to CI` |
+| `gitea.event.pull_request.head.ref`
`gitea.event.pull_request.head.sha`
`gitea.event.pull_request.head.repo.full_name` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The source branch of the pull request. | `feature-branch` |
+| `gitea.event.pull_request.base.ref`
`gitea.event.pull_request.base.sha` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The target branch of the pull request. | `main` |
+| `gitea.event.review.type` | `pull_request_review`, `pull_request_review_comment` | The kind of review: `pull_request_review_approved`, `pull_request_review_rejected` or `pull_request_review_comment`. GitHub uses `review.state` with the values `approved`, `changes_requested` and `commented`. | `pull_request_review_approved` |
+| `gitea.event.review.content` | `pull_request_review`, `pull_request_review_comment` | The body of the review. GitHub names this field `review.body`. | `Ship it` |
+| `gitea.event.changes.title.from`
`gitea.event.changes.body.from` | `issues`, `issue_comment`, `pull_request` | The previous value. Only set when `action` is `edited`. | `Old title` |
+| `gitea.event.release.tag_name`
`gitea.event.release.name`
`gitea.event.release.body`
`gitea.event.release.draft`
`gitea.event.release.prerelease` | `release` | The release the event happened on. | `v1.2.3` |
+| `gitea.event.package.name`
`gitea.event.package.type`
`gitea.event.package.version` | `registry_package` | The package the event happened on. | `gitea` |
+| `gitea.event.workflow_run.id`
`gitea.event.workflow_run.event`
`gitea.event.workflow_run.status`
`gitea.event.workflow_run.conclusion`
`gitea.event.workflow_run.head_branch`
`gitea.event.workflow_run.head_sha` | `workflow_run` | The workflow run that the event reports on. | `success` |
+
+`schedule` runs have no webhook of their own. Their payload is the payload of the push that registered the schedule, with `schedule`, `repository`, `sender` and, for organization-owned repositories, `organization` filled in.
+Only those fields are meaningful, and `sender.login` is always `gitea-actions`.
+
+## User-defined variables
+
+You can create configuration variables on the user, organization and repository level.
+The level of the variable depends on where you created it. When creating a variable, the
+key will be converted to uppercase. You need use uppercase on the yaml file.
+
+### Naming conventions
+
+The following rules apply to variable names:
+
+- Variable names can only contain alphanumeric characters (`[a-z]`, `[A-Z]`, `[0-9]`) or underscores (`_`). Spaces are not allowed.
+- Variable names must not start with the `GITHUB_` and `GITEA_` prefix.
+- Variable names must not start with a number.
+- Variable names are case-insensitive.
+- Variable names must be unique at the level they are created at.
+- Variable names must not start with `CI`.
+
+### Using variables
+
+After creating configuration variables, they will be automatically filled in the `vars` context.
+They can be accessed through expressions like `${{ vars.VARIABLE_NAME }}` in the workflow.
+
+### Precedence
+
+If a variable with the same name exists at multiple levels, the variable at the lowest level takes precedence:
+A repository variable will always be chosen over an organization/user variable.
diff --git a/versioned_docs/version-1.27/usage/actions/faq.md b/versioned_docs/version-1.27/usage/actions/faq.md
index 739154e8..fcf1015c 100644
--- a/versioned_docs/version-1.27/usage/actions/faq.md
+++ b/versioned_docs/version-1.27/usage/actions/faq.md
@@ -149,22 +149,26 @@ In case you fork Gitea Runner to create your own version: Please contribute the
All events listed in this table are supported events and are compatible with GitHub.
For events supported only by GitHub, see GitHub's [documentation](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows).
-| trigger event | activity types |
-|-----------------------------|--------------------------------------------------------------------------------------------------------------------------|
-| create | not applicable |
-| delete | not applicable |
-| fork | not applicable |
-| gollum | not applicable |
-| push | not applicable |
-| issues | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled` |
-| issue_comment | `created`, `edited`, `deleted` |
-| pull_request | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronized`, `labeled`, `unlabeled` |
-| pull_request_review | `submitted`, `edited` |
-| pull_request_review_comment | `created`, `edited` |
-| release | `published`, `edited` |
-| registry_package | `published` |
-| workflow_dispatch | not applicable |
-| workflow_run | `requested`, `completed` |
+| trigger event | activity types |
+|----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| create | not applicable |
+| delete | not applicable |
+| fork | not applicable |
+| gollum | not applicable |
+| push | not applicable |
+| schedule | not applicable |
+| workflow_dispatch | not applicable |
+| workflow_call | not applicable |
+| issues | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled` |
+| issue_comment | `created`, `edited`, `deleted` |
+| pull_request
pull_request_target | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronize`, `labeled`, `unlabeled`, `milestoned`, `demilestoned`, `review_requested`, `review_request_removed` |
+| pull_request_review | `submitted`, `edited` |
+| pull_request_review_comment | `created`, `edited` |
+| release | `published`, `edited` |
+| registry_package | `published` |
+| workflow_run | `requested`, `in_progress`, `completed` |
+
+> Without an explicit `types:` filter, `pull_request` and `pull_request_target` only run on `opened`, `reopened` and `synchronize`, matching GitHub. All other events run on every activity type they support.
> For `pull_request` events, in [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request), the `ref` is `refs/pull/:prNumber/merge`, which is a reference to the merge commit preview. However, Gitea has no such reference.
> Therefore, the `ref` in Gitea Actions is `refs/pull/:prNumber/head`, which points to the head of pull request rather than the preview of the merge commit.
diff --git a/versioned_docs/version-1.27/usage/actions/variables.md b/versioned_docs/version-1.27/usage/actions/variables.md
index e288638d..958ed127 100644
--- a/versioned_docs/version-1.27/usage/actions/variables.md
+++ b/versioned_docs/version-1.27/usage/actions/variables.md
@@ -6,80 +6,10 @@ sidebar_position: 25
# Variables
-## User-defined variables
-
-You can create configuration variables on the user, organization and repository level.
-The level of the variable depends on where you created it. When creating a variable, the
-key will be converted to uppercase. You need use uppercase on the yaml file.
-
-### Naming conventions
-
-The following rules apply to variable names:
-
-- Variable names can only contain alphanumeric characters (`[a-z]`, `[A-Z]`, `[0-9]`) or underscores (`_`). Spaces are not allowed.
-- Variable names must not start with the `GITHUB_` and `GITEA_` prefix.
-- Variable names must not start with a number.
-- Variable names are case-insensitive.
-- Variable names must be unique at the level they are created at.
-- Variable names must not start with `CI`.
-
-### Using variables
-
-After creating configuration variables, they will be automatically filled in the `vars` context.
-They can be accessed through expressions like `${{ vars.VARIABLE_NAME }}` in the workflow.
-
-### Precedence
-
-If a variable with the same name exists at multiple levels, the variable at the lowest level takes precedence:
-A repository variable will always be chosen over an organization/user variable.
-
-## Pre-defined context variables
-
-These variables are available in workflow expressions via `${{ gitea. }}`. For compatibility, `${{ github. }}` works as an alias.
-
-| Name | Description | Example |
-|---|---|---|
-| `gitea.action`
`github.action` | The name of the action currently running, or the `id` of a step. | `__run` |
-| `gitea.action_path`
`github.action_path` | The path where an action is located. Only supported in composite actions. | `/home/runner/work/_actions/actions/checkout/v4` |
-| `gitea.action_ref`
`github.action_ref` | The ref of the action being executed. | `v4` |
-| `gitea.action_repository`
`github.action_repository` | The owner and repository name of the action. | `actions/checkout` |
-| `gitea.action_status`
`github.action_status` | The current result of a composite action. | `success` |
-| `gitea.actor`
`github.actor` | The username of the user that triggered the initial workflow run. | `silverwind` |
-| `gitea.api_url`
`github.api_url` | The URL of the REST API. | `https://gitea.com/api/v1` |
-| `gitea.base_ref`
`github.base_ref` | The target branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `main` |
-| `gitea.env`
`github.env` | Path on the runner to the file that sets environment variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
-| `gitea.event`
`github.event` | The full event webhook payload as an object. | `{...}` |
-| `gitea.event_name`
`github.event_name` | The name of the event that triggered the workflow run. | `push` |
-| `gitea.event_path`
`github.event_path` | Path on the runner to the file containing the full event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
-| `gitea.head_ref`
`github.head_ref` | The source branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `feature-branch` |
-| `gitea.job`
`github.job` | The `job_id` of the current job. | `build` |
-| `gitea.ref`
`github.ref` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
-| `gitea.ref_name`
`github.ref_name` | The short ref name. | `main` |
-| `gitea.ref_protected`
`github.ref_protected` | `true` if branch protections are configured for the ref that triggered the workflow run. | `true` |
-| `gitea.ref_type`
`github.ref_type` | The type of ref: `branch` or `tag`. | `branch` |
-| `gitea.path`
`github.path` | Path on the runner to the file that sets system `PATH` variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
-| `gitea.repository`
`github.repository` | The owner and repository name. | `gitea/docs` |
-| `gitea.repository_owner`
`github.repository_owner` | The repository owner's username. | `gitea` |
-| `gitea.repositoryUrl`
`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.com/gitea/docs` |
-| `gitea.retention_days`
`github.retention_days` | The number of days that workflow run logs and artifacts are kept. | `90` |
-| `gitea.run_id`
`github.run_id` | A unique number for each workflow run within a repository. Does not change on re-run. | `1234` |
-| `gitea.run_number`
`github.run_number` | A unique number for each run of a particular workflow. Starts at 1 and increments with each new run. | `42` |
-| `gitea.run_attempt`
`github.run_attempt` | A unique number for each re-run attempt. Starts at 1 and increments with each re-run. | `1` |
-| `gitea.secret_source`
`github.secret_source` | The source of a secret used in a workflow. Always `Actions` in Gitea. | `Actions` |
-| `gitea.server_url`
`github.server_url` | The URL of the Gitea instance. | `https://gitea.com` |
-| `gitea.sha`
`github.sha` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
-| `gitea.token`
`github.token` | A token to authenticate on behalf of the Gitea App installed on the repository. See [Token permissions](token-permissions.md). | `ghs_***` |
-| `gitea.triggering_actor`
`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `silverwind` |
-| `gitea.workflow`
`github.workflow` | The name of the workflow. If unnamed, the full path of the workflow file. | `CI` |
-| `gitea.workspace`
`github.workspace` | The default working directory on the runner and the default location of your repository when using the `checkout` action. | `/workspace/gitea/docs` |
-| `gitea.gitea_default_actions_url` | The default URL for downloading actions. Gitea-specific. | `https://github.com` |
-
-## Pre-defined environment variables
+## Environment variables
These environment variables are set automatically in every workflow run and can be accessed directly (e.g. `$CI` in shell scripts).
-### Standard environment variables
-
| Name | Description | Example |
|---|---|---|
| `CI` | Always set to `true`. | `true` |
@@ -138,3 +68,124 @@ These are used internally by the runner and actions. They are typically not need
| `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.com` |
| `ACTIONS_RUNTIME_TOKEN` | Authentication token for the Actions pipeline API. | `***` |
| `ACTIONS_RUNTIME_URL` | URL for the Gitea Actions pipeline API. | `https://gitea.com/api/actions_pipeline/` |
+
+## Context variables
+
+These variables are available in workflow expressions via `${{ gitea. }}`. For compatibility, `${{ github. }}` works as an alias.
+
+| Name | Description | Example |
+|---|---|---|
+| `gitea.action`
`github.action` | The name of the action currently running, or the `id` of a step. | `__run` |
+| `gitea.action_path`
`github.action_path` | The path where an action is located. Only supported in composite actions. | `/home/runner/work/_actions/actions/checkout/v4` |
+| `gitea.action_ref`
`github.action_ref` | The ref of the action being executed. | `v4` |
+| `gitea.action_repository`
`github.action_repository` | The owner and repository name of the action. | `actions/checkout` |
+| `gitea.action_status`
`github.action_status` | The current result of a composite action. | `success` |
+| `gitea.actor`
`github.actor` | The username of the user that triggered the initial workflow run. | `silverwind` |
+| `gitea.api_url`
`github.api_url` | The URL of the REST API. | `https://gitea.com/api/v1` |
+| `gitea.base_ref`
`github.base_ref` | The target branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `main` |
+| `gitea.env`
`github.env` | Path on the runner to the file that sets environment variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
+| `gitea.event`
`github.event` | The full event webhook payload as an object. See [Event payload](#event-payload). | `{...}` |
+| `gitea.event_name`
`github.event_name` | The name of the event that triggered the workflow run. | `push` |
+| `gitea.event_path`
`github.event_path` | Path on the runner to the file containing the full event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
+| `gitea.head_ref`
`github.head_ref` | The source branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `feature-branch` |
+| `gitea.job`
`github.job` | The `job_id` of the current job. | `build` |
+| `gitea.ref`
`github.ref` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
+| `gitea.ref_name`
`github.ref_name` | The short ref name. | `main` |
+| `gitea.ref_protected`
`github.ref_protected` | `true` if branch protections are configured for the ref that triggered the workflow run. | `true` |
+| `gitea.ref_type`
`github.ref_type` | The type of ref: `branch` or `tag`. | `branch` |
+| `gitea.path`
`github.path` | Path on the runner to the file that sets system `PATH` variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
+| `gitea.repository`
`github.repository` | The owner and repository name. | `gitea/docs` |
+| `gitea.repository_owner`
`github.repository_owner` | The repository owner's username. | `gitea` |
+| `gitea.repositoryUrl`
`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.com/gitea/docs` |
+| `gitea.retention_days`
`github.retention_days` | The number of days that workflow run logs and artifacts are kept. | `90` |
+| `gitea.run_id`
`github.run_id` | A unique number for each workflow run within a repository. Does not change on re-run. | `1234` |
+| `gitea.run_number`
`github.run_number` | A unique number for each run of a particular workflow. Starts at 1 and increments with each new run. | `42` |
+| `gitea.run_attempt`
`github.run_attempt` | A unique number for each re-run attempt. Starts at 1 and increments with each re-run. | `1` |
+| `gitea.secret_source`
`github.secret_source` | The source of a secret used in a workflow. Always `Actions` in Gitea. | `Actions` |
+| `gitea.server_url`
`github.server_url` | The URL of the Gitea instance. | `https://gitea.com` |
+| `gitea.sha`
`github.sha` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
+| `gitea.token`
`github.token` | A token to authenticate on behalf of the Gitea App installed on the repository. See [Token permissions](token-permissions.md). | `ghs_***` |
+| `gitea.triggering_actor`
`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `silverwind` |
+| `gitea.workflow`
`github.workflow` | The name of the workflow. If unnamed, the full path of the workflow file. | `CI` |
+| `gitea.workspace`
`github.workspace` | The default working directory on the runner and the default location of your repository when using the `checkout` action. | `/workspace/gitea/docs` |
+| `gitea.gitea_default_actions_url` | The default URL for downloading actions. Gitea-specific. | `https://github.com` |
+
+### Event payload
+
+`gitea.event` is the webhook payload of the event that triggered the run, so which fields exist depends on `gitea.event_name`.
+The same payload is written as JSON to the file at `gitea.event_path`.
+
+Payloads use Gitea's webhook format, which is close to GitHub's but not identical. Differences are noted below.
+Reading a field that the payload does not have returns an empty value instead of failing, so `${{ gitea.event.pull_request.number }}` is empty on a `push` run.
+
+These fields exist in almost every payload:
+
+| Name | Description | Example |
+|---|---|---|
+| `gitea.event.action` | The activity type. Only set for events that have activity types, see [supported events](faq.md#what-workflow-trigger-events-does-gitea-support). | `opened` |
+| `gitea.event.repository.full_name` | The owner and name of the repository. | `gitea/docs` |
+| `gitea.event.repository.default_branch` | The default branch of the repository. | `main` |
+| `gitea.event.repository.private` | Whether the repository is private. | `false` |
+| `gitea.event.repository.html_url` | The HTML URL of the repository. | `https://gitea.com/gitea/docs` |
+| `gitea.event.sender.login` | The username of the user that triggered the event. Also available as `sender.username`. | `silverwind` |
+
+The remaining fields are specific to one or a few events:
+
+| Name | Events | Description | Example |
+|---|---|---|---|
+| `gitea.event.schedule` | `schedule` | The cron expression that triggered the run. | `*/5 * * * *` |
+| `gitea.event.inputs.` | `workflow_dispatch`, `workflow_call` | A raw input value. Prefer `${{ inputs. }}`, which also applies the input's `default`. | `true` |
+| `gitea.event.workflow` | `workflow_dispatch` | The file name of the dispatched workflow. | `ci.yaml` |
+| `gitea.event.ref` | `push`, `create`, `delete`, `workflow_dispatch` | The ref of the event. Unlike GitHub, `create` and `delete` use the full ref instead of the short name. | `refs/heads/main` |
+| `gitea.event.ref_type` | `create`, `delete` | The type of ref: `branch` or `tag`. | `tag` |
+| `gitea.event.before`
`gitea.event.after` | `push` | The commit SHA before and after the push. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
+| `gitea.event.commits` | `push` | The commits contained in the push, each with `id`, `message`, `url`, `author`, `added`, `removed` and `modified`. | `[{...}]` |
+| `gitea.event.head_commit.message` | `push` | The message of the most recent commit of the push. | `fix: broken link` |
+| `gitea.event.total_commits` | `push` | The number of commits in the push. Gitea-specific. | `3` |
+| `gitea.event.compare_url` | `push` | The URL comparing `before` with `after`. GitHub names this field `compare`. | `https://gitea.com/gitea/docs/compare/a1b2c3d...e5f6a1b` |
+| `gitea.event.pusher.login` | `push` | The username of the user that pushed. | `silverwind` |
+| `gitea.event.forkee.full_name` | `fork` | The owner and name of the new fork. | `silverwind/docs` |
+| `gitea.event.page` | `gollum` | The name of the wiki page. | `Home` |
+| `gitea.event.number` | `issues`, `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The index of the issue or pull request. Not set for `issue_comment`, use `gitea.event.issue.number` there. | `386` |
+| `gitea.event.issue.number`
`gitea.event.issue.title`
`gitea.event.issue.body`
`gitea.event.issue.state`
`gitea.event.issue.labels`
`gitea.event.issue.user.login` | `issues`, `issue_comment` | The issue the event happened on. | `Expand gitea.event in actions docs` |
+| `gitea.event.comment.body` | `issue_comment` | The body of the comment. | `LGTM` |
+| `gitea.event.is_pull` | `issue_comment` | Whether the comment was made on a pull request. Gitea-specific, GitHub sets `issue.pull_request` on the issue object instead. | `true` |
+| `gitea.event.pull_request.number`
`gitea.event.pull_request.title`
`gitea.event.pull_request.body`
`gitea.event.pull_request.draft`
`gitea.event.pull_request.merged`
`gitea.event.pull_request.state`
`gitea.event.pull_request.labels`
`gitea.event.pull_request.user.login` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The pull request the event happened on. | `Add caching to CI` |
+| `gitea.event.pull_request.head.ref`
`gitea.event.pull_request.head.sha`
`gitea.event.pull_request.head.repo.full_name` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The source branch of the pull request. | `feature-branch` |
+| `gitea.event.pull_request.base.ref`
`gitea.event.pull_request.base.sha` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The target branch of the pull request. | `main` |
+| `gitea.event.review.type` | `pull_request_review`, `pull_request_review_comment` | The kind of review: `pull_request_review_approved`, `pull_request_review_rejected` or `pull_request_review_comment`. GitHub uses `review.state` with the values `approved`, `changes_requested` and `commented`. | `pull_request_review_approved` |
+| `gitea.event.review.content` | `pull_request_review`, `pull_request_review_comment` | The body of the review. GitHub names this field `review.body`. | `Ship it` |
+| `gitea.event.changes.title.from`
`gitea.event.changes.body.from` | `issues`, `issue_comment`, `pull_request` | The previous value. Only set when `action` is `edited`. | `Old title` |
+| `gitea.event.release.tag_name`
`gitea.event.release.name`
`gitea.event.release.body`
`gitea.event.release.draft`
`gitea.event.release.prerelease` | `release` | The release the event happened on. | `v1.2.3` |
+| `gitea.event.package.name`
`gitea.event.package.type`
`gitea.event.package.version` | `registry_package` | The package the event happened on. | `gitea` |
+| `gitea.event.workflow_run.id`
`gitea.event.workflow_run.event`
`gitea.event.workflow_run.status`
`gitea.event.workflow_run.conclusion`
`gitea.event.workflow_run.head_branch`
`gitea.event.workflow_run.head_sha` | `workflow_run` | The workflow run that the event reports on. | `success` |
+
+`schedule` runs have no webhook of their own. Their payload is the payload of the push that registered the schedule, with `schedule`, `repository`, `sender` and, for organization-owned repositories, `organization` filled in.
+Only those fields are meaningful, and `sender.login` is always `gitea-actions`.
+
+## User-defined variables
+
+You can create configuration variables on the user, organization and repository level.
+The level of the variable depends on where you created it. When creating a variable, the
+key will be converted to uppercase. You need use uppercase on the yaml file.
+
+### Naming conventions
+
+The following rules apply to variable names:
+
+- Variable names can only contain alphanumeric characters (`[a-z]`, `[A-Z]`, `[0-9]`) or underscores (`_`). Spaces are not allowed.
+- Variable names must not start with the `GITHUB_` and `GITEA_` prefix.
+- Variable names must not start with a number.
+- Variable names are case-insensitive.
+- Variable names must be unique at the level they are created at.
+- Variable names must not start with `CI`.
+
+### Using variables
+
+After creating configuration variables, they will be automatically filled in the `vars` context.
+They can be accessed through expressions like `${{ vars.VARIABLE_NAME }}` in the workflow.
+
+### Precedence
+
+If a variable with the same name exists at multiple levels, the variable at the lowest level takes precedence:
+A repository variable will always be chosen over an organization/user variable.