diff --git a/docs/usage/actions/variables.md b/docs/usage/actions/variables.md index 6ca4492e..d6de94a6 100644 --- a/docs/usage/actions/variables.md +++ b/docs/usage/actions/variables.md @@ -9,53 +9,67 @@ sidebar_position: 25 ## Environment variables These environment variables are set automatically in every workflow run and can be accessed directly (e.g. `$CI` in shell scripts). +A `GITEA_*` name listed with a `GITHUB_*` name holds the same value. | Name | Description | Example | |---|---|---| +| `ACT` | Always set to `true`, unless the runner is configured with `runner.set_act_env: false`. | `true` | | `CI` | Always set to `true`. | `true` | -| `GITEA_ACTIONS` | Always set to `true`. Useful to distinguish Gitea Actions from other CI systems. | `true` | -| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `1.0.8` | -| `GITEA_DOCKER_WORKSPACE` | The workspace path as the Docker daemon sees it, for bind mounts into containers a job starts, e.g. `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data` in a compose file. Only set for jobs running in a container. | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42_***/_data` | -| `GITEA_ENV`
`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` | -| `GITEA_OUTPUT`
`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/home/runner/work/_temp/_runner_file_commands/set_output_***` | -| `GITEA_PATH`
`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` | -| `GITEA_STATE`
`GITHUB_STATE` | Path to the file that sets step state variables. | `/home/runner/work/_temp/_runner_file_commands/save_state_***` | -| `GITEA_STEP_SUMMARY`
`GITHUB_STEP_SUMMARY` | Path to the file for writing job summaries. | `/home/runner/work/_temp/_runner_file_commands/step_summary_***` | -| `GITHUB_ACTIONS` | Always set to `true`. | `true` | -| `GITHUB_ACTION` | The name of the action currently running, or the step `id`. | `__run` | -| `GITHUB_ACTION_PATH` | The path where the action is located. | `/home/runner/work/_actions/actions/checkout/v4` | -| `GITHUB_ACTION_REF` | The ref of the action being executed. | `v4` | -| `GITHUB_ACTION_REPOSITORY` | The owner and repository of the action. | `actions/checkout` | -| `GITHUB_ACTOR` | The username of the user that triggered the workflow. | `silverwind` | -| `GITHUB_API_URL` | The URL of the REST API. | `https://gitea.com/api/v1` | -| `GITHUB_BASE_REF` | The target branch of a pull request. | `main` | -| `GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. | `push` | -| `GITHUB_EVENT_PATH` | Path to the file containing the event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` | -| `GITHUB_GRAPHQL_URL` | Empty in Gitea (GraphQL is not supported). | _(empty)_ | -| `GITHUB_HEAD_REF` | The source branch of a pull request. | `feature-branch` | -| `GITHUB_JOB` | The `job_id` of the current job. | `build` | -| `GITHUB_REF` | The fully-formed ref that triggered the workflow. | `refs/heads/main` | -| `GITHUB_REF_NAME` | The short ref name. | `main` | -| `GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` | -| `GITHUB_REPOSITORY` | The owner and repository name. | `gitea/docs` | -| `GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `gitea` | -| `GITHUB_RETENTION_DAYS` | The number of days that artifacts are kept, empty when kept forever. | `90` | -| `GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` | -| `GITHUB_RUN_ID` | A unique number for each workflow run. | `1234` | -| `GITHUB_RUN_NUMBER` | A unique number for each run of a particular workflow. | `42` | -| `GITHUB_SERVER_URL` | The URL of the Gitea instance. | `https://gitea.com` | -| `GITHUB_SHA` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` | -| `GITHUB_WORKFLOW` | The name of the workflow. | `CI` | -| `GITHUB_WORKSPACE` | The default working directory on the runner. | `/workspace/gitea/docs` | +| `GITEA_ACTION`
`GITHUB_ACTION` | The `id` of the current step, or its index when it has none. | `0` | +| `GITEA_ACTION_PATH`
`GITHUB_ACTION_PATH` | The path where the action is located. Only set in composite actions. | `/var/run/act/actions/***` | +| `GITEA_ACTION_REF`
`GITHUB_ACTION_REF` | The ref of the action being executed. | `v4` | +| `GITEA_ACTION_REPOSITORY`
`GITHUB_ACTION_REPOSITORY` | The owner and repository of the action. | `actions/checkout` | +| `GITEA_ACTIONS`
`GITHUB_ACTIONS` | Always set to `true`. `GITEA_ACTIONS` is useful to distinguish Gitea Actions from other CI systems. | `true` | +| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `v5.2.4` | +| `GITEA_ACTOR`
`GITHUB_ACTOR` | The username of the user that triggered the workflow. | `alice` | +| `GITEA_ACTOR_ID`
`GITHUB_ACTOR_ID` | The ID of the user that triggered the workflow. | `1` | +| `GITEA_API_URL`
`GITHUB_API_URL` | The URL of the REST API. | `https://gitea.example.com/api/v1` | +| `GITEA_BASE_REF`
`GITHUB_BASE_REF` | The target branch of a pull request. | `main` | +| `GITEA_DOCKER_WORKSPACE` | The workspace path as the Docker daemon sees it, for bind mounts into containers a job starts, e.g. `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data` in a compose file. Only set for jobs running in a container. | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42-***/_data` | +| `GITEA_ENV`
`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/var/run/act/workflow/envs.txt` | +| `GITEA_EVENT_NAME`
`GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. | `push` | +| `GITEA_EVENT_PATH`
`GITHUB_EVENT_PATH` | Path to the file containing the event webhook payload. | `/var/run/act/workflow/event.json` | +| `GITEA_GRAPHQL_URL`
`GITHUB_GRAPHQL_URL` | Empty in Gitea (GraphQL is not supported). | _(empty)_ | +| `GITEA_HEAD_REF`
`GITHUB_HEAD_REF` | The source branch of a pull request. | `feature-branch` | +| `GITEA_JOB`
`GITHUB_JOB` | The `job_id` of the current job. | `build` | +| `GITEA_OUTPUT`
`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/var/run/act/workflow/outputcmd.txt` | +| `GITEA_PATH`
`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/var/run/act/workflow/pathcmd.txt` | +| `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. | `true` | +| `GITEA_REF_TYPE`
`GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` | +| `GITEA_REPOSITORY`
`GITHUB_REPOSITORY` | The owner and repository name. | `owner/repo` | +| `GITEA_REPOSITORY_ID`
`GITHUB_REPOSITORY_ID` | The ID of the repository. | `123` | +| `GITEA_REPOSITORY_OWNER`
`GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `owner` | +| `GITEA_REPOSITORY_OWNER_ID`
`GITHUB_REPOSITORY_OWNER_ID` | The ID of the repository owner. | `45` | +| `GITEA_RETENTION_DAYS`
`GITHUB_RETENTION_DAYS` | The number of days that artifacts are kept, empty when kept forever. | `90` | +| `GITEA_RUN_ATTEMPT`
`GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` | +| `GITEA_RUN_ID`
`GITHUB_RUN_ID` | A unique number for each workflow run. | `1234` | +| `GITEA_RUN_NUMBER`
`GITHUB_RUN_NUMBER` | A unique number for each run of a particular workflow. | `42` | +| `GITEA_SERVER_URL`
`GITHUB_SERVER_URL` | The URL of the Gitea instance. | `https://gitea.example.com` | +| `GITEA_SHA`
`GITHUB_SHA` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` | +| `GITEA_STATE`
`GITHUB_STATE` | Path to the file that sets step state variables. | `/var/run/act/workflow/statecmd.txt` | +| `GITEA_STEP_SUMMARY`
`GITHUB_STEP_SUMMARY` | Path to the file for writing job summaries. | `/var/run/act/workflow/step-summary-0.md` | +| `GITEA_TRIGGERING_ACTOR`
`GITHUB_TRIGGERING_ACTOR` | The username of the user that initiated the workflow run. May differ from `GITEA_ACTOR` on re-runs. | `alice` | +| `GITEA_WORKFLOW`
`GITHUB_WORKFLOW` | The name of the workflow. | `CI` | +| `GITEA_WORKFLOW_SHA`
`GITHUB_WORKFLOW_SHA` | The commit SHA of the workflow file. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` | +| `GITEA_WORKSPACE`
`GITHUB_WORKSPACE` | The default working directory on the runner. | `/workspace/owner/repo` | +| `TRACEPARENT` | The W3C trace context of the job's span, so instrumented tools can add spans to the job's trace. Only set when the runner exports traces, see [Monitoring](/runner/monitoring/#opentelemetry). | `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` | +| `TRACESTATE` | Vendor-specific trace data that accompanies `TRACEPARENT`. Only set when the trace carries any. | `rojo=00f067aa0ba902b7` | ### Runner environment variables | Name | Description | Example | |---|---|---| +| `ImageOS` | The OS and release of the job's image, read by `setup-*` actions. | `ubuntu24` | | `RUNNER_ARCH` | The architecture of the runner. | `X64` | +| `RUNNER_DEBUG` | Set to `1` when the `ACTIONS_STEP_DEBUG` secret is `true`, unset otherwise. | `1` | +| `RUNNER_ENVIRONMENT` | Always set to `self-hosted`. | `self-hosted` | +| `RUNNER_NAME` | The name of the runner executing the job. | `my-runner` | | `RUNNER_OS` | The operating system of the runner. | `Linux` | | `RUNNER_TEMP` | Path to a temporary directory on the runner. | `/tmp` | | `RUNNER_TOOL_CACHE` | Path to the tool cache directory on the runner. | `/opt/hostedtoolcache` | +| `RUNNER_WORKSPACE` | The parent directory of `GITEA_WORKSPACE`. | `/workspace/owner` | ### Internal environment variables @@ -65,10 +79,10 @@ These are used internally by the runner and actions. They are typically not need |---|---|---| | `ACTIONS_CACHE_URL` | URL for the actions cache service. | `http://192.168.1.10:8088/` | | `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when `id-token: write` is granted. | `***` | -| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when `id-token: write` is granted. | `https://gitea.com/api/actions/oidc/token?` | -| `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.com` | +| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when `id-token: write` is granted. | `https://gitea.example.com/api/actions/oidc/token?` | +| `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.example.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/` | +| `ACTIONS_RUNTIME_URL` | URL for the Gitea Actions pipeline API. | `https://gitea.example.com/api/actions_pipeline/` | ## Context variables @@ -76,39 +90,39 @@ These variables are available in workflow expressions via `${{ gitea. }}`. | 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`
`github.action` | The `id` of the current step, or its index when it has none. | `0` | +| `gitea.action_path`
`github.action_path` | The path where an action is located. Only supported in composite actions. | `/var/run/act/actions/***` | | `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.actor`
`github.actor` | The username of the user that triggered the initial workflow run. | `alice` | +| `gitea.api_url`
`github.api_url` | The URL of the REST API. | `https://gitea.example.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.env`
`github.env` | Path on the runner to the file that sets environment variables from workflow commands. | `/var/run/act/workflow/envs.txt` | | `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.event_path`
`github.event_path` | Path on the runner to the file containing the full event webhook payload. | `/var/run/act/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.path`
`github.path` | Path on the runner to the file that sets system `PATH` variables from workflow commands. | `/var/run/act/workflow/pathcmd.txt` | +| `gitea.repository`
`github.repository` | The owner and repository name. | `owner/repo` | +| `gitea.repository_owner`
`github.repository_owner` | The repository owner's username. | `owner` | +| `gitea.repositoryUrl`
`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.example.com/owner/repo` | | `gitea.retention_days`
`github.retention_days` | The number of days that artifacts are kept, empty when kept forever. | `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.server_url`
`github.server_url` | The URL of the Gitea instance. | `https://gitea.example.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.token`
`github.token` | A token to authenticate on behalf of the Gitea App installed on the repository. See [Token permissions](token-permissions.md). | `***` | +| `gitea.triggering_actor`
`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `alice` | | `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.workspace`
`github.workspace` | The default working directory on the runner and the default location of your repository when using the `checkout` action. | `/workspace/owner/repo` | | `gitea.gitea_default_actions_url` | The default URL for downloading actions. Gitea-specific. | `https://github.com` | ### Event payload @@ -124,11 +138,11 @@ 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.full_name` | The owner and name of the repository. | `owner/repo` | | `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` | +| `gitea.event.repository.html_url` | The HTML URL of the repository. | `https://gitea.example.com/owner/repo` | +| `gitea.event.sender.login` | The username of the user that triggered the event. Also available as `sender.username`. | `alice` | The remaining fields are specific to one or a few events: @@ -143,12 +157,12 @@ The remaining fields are specific to one or a few events: | `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.compare_url` | `push` | The URL comparing `before` with `after`. GitHub names this field `compare`. | `https://gitea.example.com/owner/repo/compare/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2...f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5` | +| `gitea.event.pusher.login` | `push` | The username of the user that pushed. | `alice` | +| `gitea.event.forkee.full_name` | `fork` | The owner and name of the new fork. | `alice/repo` | | `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.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. | `Fix typo in README` | | `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` | diff --git a/i18n/zh-cn/docs/current/usage/actions/variables.md b/i18n/zh-cn/docs/current/usage/actions/variables.md index e139f7cd..bae1234b 100644 --- a/i18n/zh-cn/docs/current/usage/actions/variables.md +++ b/i18n/zh-cn/docs/current/usage/actions/variables.md @@ -6,10 +6,90 @@ sidebar_position: 25 # 变量 +## 环境变量 + +以下环境变量会在每次工作流运行时自动设置,可以直接访问(例如在 shell 脚本中使用 `$CI`)。 +同时列出 `GITEA_*` 和 `GITHUB_*` 名称的变量值相同。 + +| 名称 | 描述 | 示例 | +|---|---|---| +| `ACT` | 始终为 `true`,除非 Runner 配置了 `runner.set_act_env: false`。 | `true` | +| `CI` | 始终为 `true`。 | `true` | +| `GITEA_ACTION`
`GITHUB_ACTION` | 当前步骤的 `id`,未设置时为步骤的序号。 | `0` | +| `GITEA_ACTION_PATH`
`GITHUB_ACTION_PATH` | Action 所在的路径。仅在复合 Action 中设置。 | `/var/run/act/actions/***` | +| `GITEA_ACTION_REF`
`GITHUB_ACTION_REF` | 正在执行的 Action 的 ref。 | `v4` | +| `GITEA_ACTION_REPOSITORY`
`GITHUB_ACTION_REPOSITORY` | Action 的所有者和仓库名称。 | `actions/checkout` | +| `GITEA_ACTIONS`
`GITHUB_ACTIONS` | 始终为 `true`。`GITEA_ACTIONS` 可用于区分 Gitea Actions 和其他 CI 系统。 | `true` | +| `GITEA_ACTIONS_RUNNER_VERSION` | 执行工作流的 Runner 的版本。 | `v5.2.4` | +| `GITEA_ACTOR`
`GITHUB_ACTOR` | 触发工作流的用户的用户名。 | `alice` | +| `GITEA_ACTOR_ID`
`GITHUB_ACTOR_ID` | 触发工作流的用户的 ID。 | `1` | +| `GITEA_API_URL`
`GITHUB_API_URL` | REST API 的 URL。 | `https://gitea.example.com/api/v1` | +| `GITEA_BASE_REF`
`GITHUB_BASE_REF` | 拉取请求的目标分支。 | `main` | +| `GITEA_DOCKER_WORKSPACE` | Docker 守护进程所见的工作区路径,用于绑定挂载到 Job 启动的容器中,例如在 compose 文件中使用 `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data`。仅在 Job 运行于容器中时设置。 | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42-***/_data` | +| `GITEA_ENV`
`GITHUB_ENV` | 为后续步骤设置环境变量的文件路径。 | `/var/run/act/workflow/envs.txt` | +| `GITEA_EVENT_NAME`
`GITHUB_EVENT_NAME` | 触发工作流的事件名称。 | `push` | +| `GITEA_EVENT_PATH`
`GITHUB_EVENT_PATH` | 包含事件 Webhook 负载的文件路径。 | `/var/run/act/workflow/event.json` | +| `GITEA_GRAPHQL_URL`
`GITHUB_GRAPHQL_URL` | 在 Gitea 中为空(不支持 GraphQL)。 | _(空)_ | +| `GITEA_HEAD_REF`
`GITHUB_HEAD_REF` | 拉取请求的源分支。 | `feature-branch` | +| `GITEA_JOB`
`GITHUB_JOB` | 当前 Job 的 `job_id`。 | `build` | +| `GITEA_OUTPUT`
`GITHUB_OUTPUT` | 设置步骤输出参数的文件路径。 | `/var/run/act/workflow/outputcmd.txt` | +| `GITEA_PATH`
`GITHUB_PATH` | 为后续步骤添加系统 `PATH` 条目的文件路径。 | `/var/run/act/workflow/pathcmd.txt` | +| `GITEA_REF`
`GITHUB_REF` | 触发工作流的完整 ref。 | `refs/heads/main` | +| `GITEA_REF_NAME`
`GITHUB_REF_NAME` | ref 的短名称。 | `main` | +| `GITEA_REF_PROTECTED`
`GITHUB_REF_PROTECTED` | 如果触发工作流的 ref 配置了分支保护,则为 `true`。 | `true` | +| `GITEA_REF_TYPE`
`GITHUB_REF_TYPE` | ref 的类型:`branch` 或 `tag`。 | `branch` | +| `GITEA_REPOSITORY`
`GITHUB_REPOSITORY` | 所有者和仓库名称。 | `owner/repo` | +| `GITEA_REPOSITORY_ID`
`GITHUB_REPOSITORY_ID` | 仓库的 ID。 | `123` | +| `GITEA_REPOSITORY_OWNER`
`GITHUB_REPOSITORY_OWNER` | 仓库所有者的用户名。 | `owner` | +| `GITEA_REPOSITORY_OWNER_ID`
`GITHUB_REPOSITORY_OWNER_ID` | 仓库所有者的 ID。 | `45` | +| `GITEA_RETENTION_DAYS`
`GITHUB_RETENTION_DAYS` | Artifact 的保留天数,永久保留时为空。 | `90` | +| `GITEA_RUN_ATTEMPT`
`GITHUB_RUN_ATTEMPT` | 工作流运行的尝试次数。 | `1` | +| `GITEA_RUN_ID`
`GITHUB_RUN_ID` | 每次工作流运行的唯一编号。 | `1234` | +| `GITEA_RUN_NUMBER`
`GITHUB_RUN_NUMBER` | 特定工作流每次运行的唯一编号。 | `42` | +| `GITEA_SERVER_URL`
`GITHUB_SERVER_URL` | Gitea 实例的 URL。 | `https://gitea.example.com` | +| `GITEA_SHA`
`GITHUB_SHA` | 触发工作流的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` | +| `GITEA_STATE`
`GITHUB_STATE` | 设置步骤状态变量的文件路径。 | `/var/run/act/workflow/statecmd.txt` | +| `GITEA_STEP_SUMMARY`
`GITHUB_STEP_SUMMARY` | 写入 Job 摘要的文件路径。 | `/var/run/act/workflow/step-summary-0.md` | +| `GITEA_TRIGGERING_ACTOR`
`GITHUB_TRIGGERING_ACTOR` | 发起工作流运行的用户的用户名。重新运行时可能与 `GITEA_ACTOR` 不同。 | `alice` | +| `GITEA_WORKFLOW`
`GITHUB_WORKFLOW` | 工作流的名称。 | `CI` | +| `GITEA_WORKFLOW_SHA`
`GITHUB_WORKFLOW_SHA` | 工作流文件的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` | +| `GITEA_WORKSPACE`
`GITHUB_WORKSPACE` | Runner 上的默认工作目录。 | `/workspace/owner/repo` | +| `TRACEPARENT` | Job span 的 W3C 追踪上下文,供已接入追踪的工具将 span 添加到 Job 的追踪中。仅在 Runner 导出追踪数据时设置,参见[监控](/runner/monitoring/#opentelemetry)。 | `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` | +| `TRACESTATE` | 随 `TRACEPARENT` 附带的厂商特定追踪数据。仅在追踪包含此类数据时设置。 | `rojo=00f067aa0ba902b7` | + +### Runner 环境变量 + +| 名称 | 描述 | 示例 | +|---|---|---| +| `ImageOS` | Job 镜像的操作系统和版本,供 `setup-*` Action 读取。 | `ubuntu24` | +| `RUNNER_ARCH` | Runner 的架构。 | `X64` | +| `RUNNER_DEBUG` | 当 `ACTIONS_STEP_DEBUG` 密钥为 `true` 时设置为 `1`,否则不设置。 | `1` | +| `RUNNER_ENVIRONMENT` | 始终为 `self-hosted`。 | `self-hosted` | +| `RUNNER_NAME` | 执行 Job 的 Runner 的名称。 | `my-runner` | +| `RUNNER_OS` | Runner 的操作系统。 | `Linux` | +| `RUNNER_TEMP` | Runner 上临时目录的路径。 | `/tmp` | +| `RUNNER_TOOL_CACHE` | Runner 上工具缓存目录的路径。 | `/opt/hostedtoolcache` | +| `RUNNER_WORKSPACE` | `GITEA_WORKSPACE` 的父目录。 | `/workspace/owner` | + +### 内部环境变量 + +这些变量供 Runner 和 Action 内部使用,工作流中通常不需要直接使用。 + +| 名称 | 描述 | 示例 | +|---|---|---| +| `ACTIONS_CACHE_URL` | Actions 缓存服务的 URL。 | `http://192.168.1.10:8088/` | +| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | 用于 OIDC 请求的令牌。仅在授予 `id-token: write` 时设置。 | `***` | +| `ACTIONS_ID_TOKEN_REQUEST_URL` | 请求 OIDC 令牌的 URL。仅在授予 `id-token: write` 时设置。 | `https://gitea.example.com/api/actions/oidc/token?` | +| `ACTIONS_RESULTS_URL` | 存储 Artifact 的 URL。 | `https://gitea.example.com` | +| `ACTIONS_RUNTIME_TOKEN` | Actions 流水线 API 的认证令牌。 | `***` | +| `ACTIONS_RUNTIME_URL` | Gitea Actions 流水线 API 的 URL。 | `https://gitea.example.com/api/actions_pipeline/` | + +## 用户定义的变量 + 您可以创建用户、组织和仓库级别的变量。变量的级别取决于创建它的位置。当创建变量时,变量的名称会被 转换为大写,在yaml文件中引用时需要使用大写。 -## 命名规则 +### 命名规则 以下规则适用于变量名: @@ -20,11 +100,11 @@ sidebar_position: 25 - 变量名称在创建它们的级别上必须是唯一的。 - 变量名称不能为 `CI`。 -## 使用 +### 使用 创建配置变量后,它们将自动填充到 `vars` 上下文中。您可以在工作流中使用类似 `${{ vars.VARIABLE_NAME }}` 这样的表达式来使用它们。 -## 优先级 +### 优先级 如果同名变量存在于多个级别,则级别最低的变量优先。 仓库级别的变量总是比组织或者用户级别的变量优先被选中。 diff --git a/i18n/zh-tw/docs/current/usage/actions/variables.md b/i18n/zh-tw/docs/current/usage/actions/variables.md index 4a544e8f..d6b5f909 100644 --- a/i18n/zh-tw/docs/current/usage/actions/variables.md +++ b/i18n/zh-tw/docs/current/usage/actions/variables.md @@ -6,10 +6,90 @@ sidebar_position: 25 # 變量 +## 環境變量 + +以下環境變量會在每次工作流執行時自動設定,可以直接存取(例如在 shell 腳本中使用 `$CI`)。 +同時列出 `GITEA_*` 和 `GITHUB_*` 名稱的變量值相同。 + +| 名稱 | 描述 | 範例 | +|---|---|---| +| `ACT` | 始終為 `true`,除非 Runner 設定了 `runner.set_act_env: false`。 | `true` | +| `CI` | 始終為 `true`。 | `true` | +| `GITEA_ACTION`
`GITHUB_ACTION` | 目前步驟的 `id`,未設定時為步驟的序號。 | `0` | +| `GITEA_ACTION_PATH`
`GITHUB_ACTION_PATH` | Action 所在的路徑。僅在複合 Action 中設定。 | `/var/run/act/actions/***` | +| `GITEA_ACTION_REF`
`GITHUB_ACTION_REF` | 正在執行的 Action 的 ref。 | `v4` | +| `GITEA_ACTION_REPOSITORY`
`GITHUB_ACTION_REPOSITORY` | Action 的所有者和儲存庫名稱。 | `actions/checkout` | +| `GITEA_ACTIONS`
`GITHUB_ACTIONS` | 始終為 `true`。`GITEA_ACTIONS` 可用於區分 Gitea Actions 和其他 CI 系統。 | `true` | +| `GITEA_ACTIONS_RUNNER_VERSION` | 執行工作流的 Runner 的版本。 | `v5.2.4` | +| `GITEA_ACTOR`
`GITHUB_ACTOR` | 觸發工作流的使用者的使用者名稱。 | `alice` | +| `GITEA_ACTOR_ID`
`GITHUB_ACTOR_ID` | 觸發工作流的使用者的 ID。 | `1` | +| `GITEA_API_URL`
`GITHUB_API_URL` | REST API 的 URL。 | `https://gitea.example.com/api/v1` | +| `GITEA_BASE_REF`
`GITHUB_BASE_REF` | 拉取請求的目標分支。 | `main` | +| `GITEA_DOCKER_WORKSPACE` | Docker 守護程式所見的工作區路徑,用於綁定掛載到 Job 啟動的容器中,例如在 compose 檔案中使用 `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data`。僅在 Job 於容器中執行時設定。 | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42-***/_data` | +| `GITEA_ENV`
`GITHUB_ENV` | 為後續步驟設定環境變量的檔案路徑。 | `/var/run/act/workflow/envs.txt` | +| `GITEA_EVENT_NAME`
`GITHUB_EVENT_NAME` | 觸發工作流的事件名稱。 | `push` | +| `GITEA_EVENT_PATH`
`GITHUB_EVENT_PATH` | 包含事件 Webhook 負載的檔案路徑。 | `/var/run/act/workflow/event.json` | +| `GITEA_GRAPHQL_URL`
`GITHUB_GRAPHQL_URL` | 在 Gitea 中為空(不支援 GraphQL)。 | _(空)_ | +| `GITEA_HEAD_REF`
`GITHUB_HEAD_REF` | 拉取請求的來源分支。 | `feature-branch` | +| `GITEA_JOB`
`GITHUB_JOB` | 目前 Job 的 `job_id`。 | `build` | +| `GITEA_OUTPUT`
`GITHUB_OUTPUT` | 設定步驟輸出參數的檔案路徑。 | `/var/run/act/workflow/outputcmd.txt` | +| `GITEA_PATH`
`GITHUB_PATH` | 為後續步驟新增系統 `PATH` 項目的檔案路徑。 | `/var/run/act/workflow/pathcmd.txt` | +| `GITEA_REF`
`GITHUB_REF` | 觸發工作流的完整 ref。 | `refs/heads/main` | +| `GITEA_REF_NAME`
`GITHUB_REF_NAME` | ref 的短名稱。 | `main` | +| `GITEA_REF_PROTECTED`
`GITHUB_REF_PROTECTED` | 如果觸發工作流的 ref 設定了分支保護,則為 `true`。 | `true` | +| `GITEA_REF_TYPE`
`GITHUB_REF_TYPE` | ref 的類型:`branch` 或 `tag`。 | `branch` | +| `GITEA_REPOSITORY`
`GITHUB_REPOSITORY` | 所有者和儲存庫名稱。 | `owner/repo` | +| `GITEA_REPOSITORY_ID`
`GITHUB_REPOSITORY_ID` | 儲存庫的 ID。 | `123` | +| `GITEA_REPOSITORY_OWNER`
`GITHUB_REPOSITORY_OWNER` | 儲存庫所有者的使用者名稱。 | `owner` | +| `GITEA_REPOSITORY_OWNER_ID`
`GITHUB_REPOSITORY_OWNER_ID` | 儲存庫所有者的 ID。 | `45` | +| `GITEA_RETENTION_DAYS`
`GITHUB_RETENTION_DAYS` | Artifact 的保留天數,永久保留時為空。 | `90` | +| `GITEA_RUN_ATTEMPT`
`GITHUB_RUN_ATTEMPT` | 工作流執行的嘗試次數。 | `1` | +| `GITEA_RUN_ID`
`GITHUB_RUN_ID` | 每次工作流執行的唯一編號。 | `1234` | +| `GITEA_RUN_NUMBER`
`GITHUB_RUN_NUMBER` | 特定工作流每次執行的唯一編號。 | `42` | +| `GITEA_SERVER_URL`
`GITHUB_SERVER_URL` | Gitea 實例的 URL。 | `https://gitea.example.com` | +| `GITEA_SHA`
`GITHUB_SHA` | 觸發工作流的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` | +| `GITEA_STATE`
`GITHUB_STATE` | 設定步驟狀態變量的檔案路徑。 | `/var/run/act/workflow/statecmd.txt` | +| `GITEA_STEP_SUMMARY`
`GITHUB_STEP_SUMMARY` | 寫入 Job 摘要的檔案路徑。 | `/var/run/act/workflow/step-summary-0.md` | +| `GITEA_TRIGGERING_ACTOR`
`GITHUB_TRIGGERING_ACTOR` | 發起工作流執行的使用者的使用者名稱。重新執行時可能與 `GITEA_ACTOR` 不同。 | `alice` | +| `GITEA_WORKFLOW`
`GITHUB_WORKFLOW` | 工作流的名稱。 | `CI` | +| `GITEA_WORKFLOW_SHA`
`GITHUB_WORKFLOW_SHA` | 工作流檔案的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` | +| `GITEA_WORKSPACE`
`GITHUB_WORKSPACE` | Runner 上的預設工作目錄。 | `/workspace/owner/repo` | +| `TRACEPARENT` | Job span 的 W3C 追蹤上下文,供已接入追蹤的工具將 span 新增到 Job 的追蹤中。僅在 Runner 匯出追蹤資料時設定,參見[監控](/runner/monitoring/#opentelemetry)。 | `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` | +| `TRACESTATE` | 隨 `TRACEPARENT` 附帶的廠商特定追蹤資料。僅在追蹤包含此類資料時設定。 | `rojo=00f067aa0ba902b7` | + +### Runner 環境變量 + +| 名稱 | 描述 | 範例 | +|---|---|---| +| `ImageOS` | Job 映像的作業系統和版本,供 `setup-*` Action 讀取。 | `ubuntu24` | +| `RUNNER_ARCH` | Runner 的架構。 | `X64` | +| `RUNNER_DEBUG` | 當 `ACTIONS_STEP_DEBUG` 密鑰為 `true` 時設定為 `1`,否則不設定。 | `1` | +| `RUNNER_ENVIRONMENT` | 始終為 `self-hosted`。 | `self-hosted` | +| `RUNNER_NAME` | 執行 Job 的 Runner 的名稱。 | `my-runner` | +| `RUNNER_OS` | Runner 的作業系統。 | `Linux` | +| `RUNNER_TEMP` | Runner 上暫存目錄的路徑。 | `/tmp` | +| `RUNNER_TOOL_CACHE` | Runner 上工具快取目錄的路徑。 | `/opt/hostedtoolcache` | +| `RUNNER_WORKSPACE` | `GITEA_WORKSPACE` 的上層目錄。 | `/workspace/owner` | + +### 內部環境變量 + +這些變量供 Runner 和 Action 內部使用,工作流中通常不需要直接使用。 + +| 名稱 | 描述 | 範例 | +|---|---|---| +| `ACTIONS_CACHE_URL` | Actions 快取服務的 URL。 | `http://192.168.1.10:8088/` | +| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | 用於 OIDC 請求的令牌。僅在授予 `id-token: write` 時設定。 | `***` | +| `ACTIONS_ID_TOKEN_REQUEST_URL` | 請求 OIDC 令牌的 URL。僅在授予 `id-token: write` 時設定。 | `https://gitea.example.com/api/actions/oidc/token?` | +| `ACTIONS_RESULTS_URL` | 儲存 Artifact 的 URL。 | `https://gitea.example.com` | +| `ACTIONS_RUNTIME_TOKEN` | Actions 管線 API 的驗證令牌。 | `***` | +| `ACTIONS_RUNTIME_URL` | Gitea Actions 管線 API 的 URL。 | `https://gitea.example.com/api/actions_pipeline/` | + +## 使用者定義的變量 + 您可以建立使用者、組織和儲存庫級別的變量。變量的級別取決於建立它的位置。當建立變量時,變量的名稱會被 轉換為大寫,在yaml文件中引用時需要使用大寫。 -## 命名規則 +### 命名規則 以下規則適用於變量名: @@ -20,11 +100,11 @@ sidebar_position: 25 - 變量名稱在建立它們的級別上必須是唯一的。 - 變量名稱不能為 `CI`。 -## 使用 +### 使用 建立設定變量後,它們將自動填充到 `vars` 上下文中。您可以在工作流中使用類似 `${{ vars.VARIABLE_NAME }}` 這樣的表達式來使用它們。 -## 優先級 +### 優先級 如果同名變量存在於多個級別,則級別最低的變量優先。 儲存庫級別的變量總是比組織或者使用者級別的變量優先被選中。 diff --git a/runner-docs/hooks/job-hooks.md b/runner-docs/hooks/job-hooks.md index dc24f671..eb4c4982 100644 --- a/runner-docs/hooks/job-hooks.md +++ b/runner-docs/hooks/job-hooks.md @@ -31,7 +31,7 @@ The shell options of `run:` steps do not apply to hooks. Set `pipefail` and othe ## Environment and output -A hook receives the job's environment, including `runner.envs`, the workflow's `env:` and the `GITHUB_*` variables. The runner includes hook output in the job log and masks secrets as it does for step output. +A hook receives the job's environment, including `runner.envs`, the workflow's `env:` and the `GITHUB_*` and `GITEA_*` variables. The runner includes hook output in the job log and masks secrets as it does for step output. Use `$GITHUB_ENV` and `$GITHUB_PATH` to pass environment variables and paths to later steps. Mask values with `::add-mask::`: