运行时环境变量

本文档介绍插件运行时可用的系统环境变量、上下文以及运行时过程文件（ATOMGIT_ENV、ATOMGIT_OUTPUT 等）的完整说明。

流水线系统变量

当前支持如下内置的公共环境变量，可以直接引用，无需定义。

系统变量	AtomGit定义
CI	始终设置为true。
ATOMGIT_ACTION	当前正在运行的操作名称。通常为actions名称，注意：若在同一任务中多次使用相同脚本或操作，名称将包含由下划线加序号组成的后缀。例如：首次运行的脚本名称为 actionscheckout，第二次运行则为actionscheckout_2。
ATOMGIT_ACTION_PATH	GITHUB_ACTION_PATH 指向的是 Action 所在的路径。对于复合操作 (Composite Actions)：它指向包含 action.yml 文件的目录。对于 Docker 容器操作：它指向容器内包含 Action 文件的目录。注意：它与 ATOMGIT_WORKSPACE不同，后者是执行流水线（Workflow）时代码检出的根目录。
ATOMGIT_ACTION_REPOSITORY	对于执行action的步骤，此处是action的所有者和存储库名称。例如：actions/checkout。
ATOMGIT_ACTIONS	在 AtomGit Actions 运行工作流时，此变量默认设置为 true。您可以使用此变量区分测试是在本地运行还是由AtomGit Actions 运行
ATOMGIT_ACTOR	启动工作流的人员或应用程序名称
ATOMGIT_ACTOR_ID	触发初始工作流运行的用户或应用程序的账户ID。例如：1234567。请注意，此ID与操作者用户名不同。
ATOMGIT_API_URL	返回API网址。
ATOMGIT_BASE_REF	工作流运行中拉取请求的基准引用或目标分支名称。仅当触发工作流运行的事件为pull_request/merge_request或pull_request_target/merge_request_target时设置此字段。例如：main。
ATOMGIT_ENV	在运行器上指向设置工作流命令变量的文件的路径。该文件路径在当前步骤中是唯一的，且在任务的每个步骤中都会改变。例如：/home/octopus/runner/workers/0.0.3.0.version/*temp/*runner_file_commands/set_env_5215d2ef-bd44-4d6e-9fd0-afe76bb20313
ATOMGIT_EVENT_NAME	触发工作流的事件名称。例如：workflow_dispatch。
ATOMGIT_HEAD_REF	工作流运行中拉取请求的头部引用或源分支。此属性仅在触发工作流运行的事件为pull_request或pull_request_target时设置。例如：feature-branch-1。
ATOMGIT_JOB	当前工作的job_id。例如：greeting_job。
ATOMGIT_OUTPUT	在运行器上指向该文件的路径，该文件用于设置工作流命令当前步骤的输出。此文件的路径在当前步骤中是唯一的，并且在任务的每个步骤中都会改变。例如：/home/octopus/runner/workers/0.0.3.0.version/*temp/*runner_file_commands/set_output_5215d2ef-bd44-4d6e-9fd0-afe76bb20313
ATOMGIT_PATH	在运行器上用于设置系统路径变量的文件路径，该文件通过工作流命令生成。此文件路径在当前步骤中是唯一的，且在任务的每个步骤中都会改变。例如：/home/octopus/runner/workers/0.0.3.0.version/*temp/*runner_file_commands/add_path_5215d2ef-bd44-4d6e-9fd0-afe76bb20313
ATOMGIT_REF	触发工作流运行的分支或标签的完整引用。对于由推送触发的工作流，此处为被推送的分支或标签引用。对于由未合并的pull_request触发的工作流，此处为拉取请求的合并分支。若拉取请求已合并，则为head分支。对于由发布触发的工作流，此处为创建的发布标签。对于其他触发器，此处为触发工作流运行的分支或标签引用。仅当事件类型支持分支或标签时才会设置此字段。给定的引用格式完整规范：分支引用格式为 refs/heads/<分支名称>。对于除pull_request_target外的未合并拉取请求事件，引用格式为 refs/pull/<pr_number>/merge。pull_request_target事件引用基准分支。标签事件引用格式为 refs/tags/<tag_name>。例如：refs/heads/feature-branch-1。
ATOMGIT_REF_NAME	触发工作流运行的分支或标签的简短引用名称。该值与 AtomGit上显示的分支或标签名称一致。例如：feature-branch-1。 对于未合并的拉取请求，格式为 <pr_number>/merge。
ATOMGIT_REF_PROTECTED	如果为触发工作流运行的引用配置了分支保护或规则集，则为真。
ATOMGIT_REF_TYPE	触发工作流运行的引用类型。有效值为分支或标签。
ATOMGIT_REPOSITORY	所有者和存储库名称。例如，octocat/Hello-World。
ATOMGIT_REPOSITORY_ID	存储库的ID。例如：123456789。请注意，这与存储库名称不同。
ATOMGIT_REPOSITORY_OWNER	仓库所有者的名称。例如，octocat。
ATOMGIT_REPOSITORY_OWNER_ID	仓库所有者的账户ID。例如：1234567。请注意，这与所有者的姓名不同。
ATOMGIT_RETENTION_DAYS	工作流运行日志和工件的保留天数。例如，90。
ATOMGIT_RUN_ATTEMPT	每个工作流运行在存储库中的每次尝试都拥有一个唯一编号。该编号从工作流运行的首次尝试开始计数为1，并随每次重新运行递增。例如：3。
ATOMGIT_RUN_ID	每个工作流运行在存储库中都有一个唯一的编号。即使重新运行该工作流，该编号也不会改变。例如：1658821493。
ATOMGIT_RUN_NUMBER	存储库中特定工作流每次运行时生成的唯一编号。该编号从工作流首次运行时的1开始，每次新运行时递增。即使重新运行工作流，该编号也不会改变。例如：3
ATOMGIT_SERVER_URL	AtomGit服务器的 URL。例如：xxxx
ATOMGIT_SHA	触发工作流的提交SHA。该提交SHA的具体值取决于触发工作流的事件类型。更多信息请参阅《触发工作流的事件》。例如：ffac537e6cbbf934b08745a378932722df287a53。
ATOMGIT_STEP_SUMMARY	运行器上指向包含工作流命令任务摘要的文件的路径。该文件路径在当前步骤中是唯一的，且在任务的每个步骤中都会改变。例如：/home/octopus/runner/workers/0.0.3.0.version/*temp/*runner_file_commands/step_summary_1cb22d7f-5663-41a8-9ffc-13472605c76c。
ATOMGIT_TRIGGERING_ACTOR	发起工作流运行的用户的用户名。如果工作流运行是重新运行，此值可能与 ATOMGIT_ACTOR 不同。任何工作流重新运行都将使用 ATOMGIT_ACTOR 的权限，即使发起重新运行的操作者（ATOMGIT_ACTOR）具有不同的权限也是如此。
ATOMGIT_WORKFLOW	工作流的名称。例如，My test workflow。如果工作流文件未指定名称，则此变量的值为工作流文件在存储库中的完整路径。
ATOMGIT_WORKFLOW_ID	工作流的唯一标识ID
ATOMGIT_WORKFLOW_REF	工作流的引用路径。ATOMGIT_WORKFLOW_REF 包含了三个核心信息：仓库路径：组织名/仓库名。工作流文件路径：.atomgit/workflows/ 下的 YAML 文件名。引用标识 (Ref)：触发该工作流的分支名、标签名或具体的 Commit SHA。其标准格式通常如下： {owner}/{repo}/.gitcode/workflows/{filename}@{ref} 例子： octocat/hello-world/.gitcode/workflows/main.yml@refs/heads/main
ATOMGIT_WORKFLOW_SHA	工作流文件的提交SHA值。
ATOMGIT_WORKSPACE	运行器上步骤的默认工作目录。例如：/home/octopus/runner/workers/0.0.3.0.version/worker_dir/placeholder_repo
RUNNER_ARCH	执行该任务的运行程序的架构。可能值包括X86、X64、ARM或ARM64
RUNNER_ENVIRONMENT	定义资源池类型执行任务的运行器环境。可能值包括：gitcode-hosted（AtomGit公共资源池，由AtomGit提供）self-hosted（自托管资源池，由用户配置）
RUNNER_NAME	执行任务的运行器名称。该名称在工作流运行中可能不唯一，因为存储库和组织层级的运行器可能使用相同名称。例如：托管代理
RUNNER_OS	执行该任务的运行程序的操作系统。可能值为Linux、Windows或macOS。例如，Windows
RUNNER_TEMP	运行器上的临时目录路径。该目录在每个任务开始和结束时会被清空。请注意，如果运行器的用户账户没有删除权限，文件将不会被移除。例如：D:\a_temp
RUNNER_TOOL_CACHE	指向包含 AtomGit托管运行器预装工具的目录的路径。有关详细信息，请参阅 AtomGit托管运行器。例如：C:\hostedtoolcache\windows

---

上下文

可用上下文

以下列举一级上下文定义，全量上下文定义可查阅主文档中的上下文章节。

上下文名称	类型	描述
atomgit	object	关于工作流运行的信息。
env	object	包含在工作流、任务或步骤中设置的变量。
vars	object	包含在仓库、组织或环境级别设置的变量。
job	object	关于当前正在运行的任务的信息。
jobs	object	仅对于可重用工作流，包含来自可重用工作流的任务输出。
steps	object	关于当前任务中已运行的步骤的信息。
runner	object	关于正在运行当前任务的运行器的信息。
secrets	object	包含可用的工作流运行的密钥的名称和值。
strategy	object	关于当前任务的矩阵执行策略的信息。
matrix	object	包含在工作流中定义的、适用于当前任务的矩阵属性。
inputs	object	包含传递给操作、可重用工作流或手动触发的工作流的输入属性。

如果您尝试引用不存在的属性，它将计算为空字符串。

确定何时使用上下文

• 默认环境变量：这些环境变量仅存在于执行您任务的运行器上。更多信息，请参阅 变量参考。

• 上下文：您可以在工作流中的任何时候使用大多数上下文，包括 默认变量 不可用的时候。例如，您可以将上下文与表达式一起使用，在任务路由到runner执行之前执行初始处理；这允许您使用与条件 if 关键字相关的上下文来确定是否应运行某个步骤。一旦任务开始运行，您还可以从执行任务的运行器中检索上下文变量，例如 runner.os。

以下示例演示了如何在任务中一起使用这些不同类型的变量：

name: CI  
on: push  
jobs:  
  prod-check:
    name: 生产检查
    if: ${{ atomgit.ref == 'refs/heads/main' }}
    runs-on: default 
    steps:  
      - run: echo "Deploying to production server on branch $ATOMGIT_REF"

在此示例中，if 语句检查 atomgit.ref 上下文以确定当前分支名称；如果名称是 refs/heads/main，则执行后续步骤。if 检查由 AtomGit Pipeline 处理，并且只有当结果为 true 时任务才被发送到执行环境。一旦任务被发送到执行环境，步骤就会执行，并引用来自 $ATOMGIT_REF 变量。

运行时过程文件说明

AtomGit Runner 在运行流水线时，会在执行机上生成一组临时过程文件，并通过环境变量将文件路径暴露给当前 step 或 action。用户可以通过向这些文件写入内容，与 runner 进行数据交互，例如设置环境变量、设置 step 输出、追加 PATH、生成 Job Summary、在 action 的 pre/main/post 生命周期之间传递状态等。

需要注意：ATOMGIT_ENV、ATOMGIT_OUTPUT、ATOMGIT_PATH、ATOMGIT_STEP_SUMMARY 这类文件的路径通常是“当前 step 唯一”的，不同 step 中路径会变化；写入后的效果一般从后续 step 或 runner 汇总阶段开始生效。

1. 全量过程文件总表

系统变量	文件类型	主要用途	生效范围	典型写入格式	是否推荐用户直接使用
ATOMGIT_ENV	环境变量文件	设置后续 step 可读取的环境变量	当前 job 的后续 step	echo "NAME=value" >> "$ATOMGIT_ENV"	是
ATOMGIT_OUTPUT	Step 输出文件	设置当前 step 的 output，供后续 step、job output 或 reusable workflow 使用	当前 step 输出；通过 steps.<id>.outputs 引用	echo "name=value" >> "$ATOMGIT_OUTPUT"	是
ATOMGIT_PATH	PATH 追加文件	将目录追加到系统 PATH，让后续 step 可直接调用目录下命令	当前 job 的后续 step/action	echo "/path/to/bin" >> "$ATOMGIT_PATH"	是
ATOMGIT_STEP_SUMMARY	Step/Job 摘要文件	生成 Markdown 格式的 Job Summary，展示在流水线运行摘要页面	当前 step 写入，job 结束后汇总展示	echo "### Summary" >> "$ATOMGIT_STEP_SUMMARY"	是

2. ATOMGIT_ENV：设置后续步骤环境变量

用途

ATOMGIT_ENV 用于向当前 job 的后续 step 注入环境变量。当前 step 写入后，当前 step 自身不能读取新值，但后续 step 可以读取。

不建议通过 ATOMGIT_ENV 覆盖 runner 默认注入的系统变量，例如 ATOMGIT_*、RUNNER_* 等变量。系统变量通常由平台控制，用户自定义覆盖可能不会生效，也可能造成行为不可预期。

使用场景

适合在流水线执行过程中动态计算变量，并在后续步骤中复用。

场景	示例
动态生成版本号	从 tag、commit、时间戳生成 BUILD_VERSION
多步骤共享路径	构建产物目录、临时目录、工具安装目录
共享部署参数	环境名称、镜像 tag、发布渠道
共享脚本计算结果	检测结果、变更模块列表、构建开关

使用案例：设置构建版本号

name: env-example

on:
  push:

jobs:
  build:
    name: 构建
    runs-on: default
    steps:
      - name: Generate build version
        run: |
          VERSION="1.0.${ATOMGIT_RUN_NUMBER}"
          echo "BUILD_VERSION=$VERSION" >> "$ATOMGIT_ENV"

      - name: Use build version
        run: |
          echo "Current build version is $BUILD_VERSION"

使用案例：写入多行环境变量

多行变量可以使用 delimiter 语法：

steps:
  - name: Set multiline env
    run: |
      {
        echo 'CHANGELOG<<EOF'
        echo '- add login feature'
        echo '- fix build script'
        echo EOF
      } >> "$ATOMGIT_ENV"

  - name: Use multiline env
    run: |
      echo "$CHANGELOG"

使用多行写入时，delimiter 不应出现在变量内容的独立行中；如果内容完全不可控，建议写入普通文件，再通过文件路径传递。

3. ATOMGIT_OUTPUT：设置 step 输出

用途

ATOMGIT_OUTPUT 用于设置当前 step 的输出参数。后续 step 可以通过 ${{ steps.<step_id>.outputs.<output_name> }} 读取该值。设置输出的 step 必须配置 id，否则后续 step 无法通过 steps.<id>.outputs 引用。

使用场景

适合表达“一个步骤的结构化结果”，比直接写环境变量更适合做步骤间、任务间的数据传递。

场景	示例
获取构建结果	输出 artifact_name、artifact_path
动态决定后续行为	输出 should_deploy=true/false
生成镜像信息	输出 image_tag、image_digest
多 job 传参	先设置 step output，再映射为 job output
自定义 action 输出	action 内部将计算结果暴露给调用方

使用案例：step 之间传递输出

name: output-example

on:
  push:

jobs:
  build:
    name: 构建
    runs-on: default
    steps:
      - name: Generate image tag
        id: meta
        run: |
          IMAGE_TAG="app-${ATOMGIT_SHA::7}"
          echo "image_tag=$IMAGE_TAG" >> "$ATOMGIT_OUTPUT"

      - name: Use image tag
        run: |
          echo "Image tag is ${{ steps.meta.outputs.image_tag }}"

使用案例：job 之间传递输出

name: job-output-example

on:
  push:

jobs:
  build:
    name: 构建
    runs-on: ubuntu-latest
    outputs:
      image_tag: ${{ steps.meta.outputs.image_tag }}
    steps:
      - name: Generate image tag
        id: meta
        run: |
          echo "image_tag=app-${ATOMGIT_SHA}" >> "$ATOMGIT_OUTPUT"

  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy
        run: |
          echo "Deploy image tag: ${{ needs.build.outputs.image_tag }}"

跨 job 传递数据时，通常需要先通过 ATOMGIT_OUTPUT 设置 step output，再通过 jobs.<job_id>.outputs 将 step output 映射成 job output，最后由下游 job 通过 needs.<job_id>.outputs.<output_name> 获取。

4. ATOMGIT_PATH：向 PATH 中追加命令目录

用途

ATOMGIT_PATH 用于将一个目录追加到系统 PATH 中，使后续 step 或 action 可以直接调用该目录下的可执行文件。写入后，当前 step 不能立即访问更新后的 PATH，后续 step 才能访问。

使用场景

适合在流水线中临时安装 CLI、脚本工具或构建工具，并让后续步骤直接调用。

场景	示例
安装自定义 CLI	下载 mycli 到 $HOME/.local/bin
使用项目内脚本	将 scripts/bin 加入 PATH
准备语言工具链	将临时安装的 Go/Node/Python 工具目录加入 PATH
兼容多平台执行	根据 OS 写入不同工具目录

使用案例：安装 CLI 后直接调用

name: path-example

on:
  push:

jobs:
  use-cli:
    name: 使用 CLI
    runs-on: ubuntu-latest
    steps:
      - name: Install custom cli
        run: |
          mkdir -p "$HOME/.local/bin"
          cat > "$HOME/.local/bin/hello-cli" <<'EOF'
          #!/usr/bin/env bash
          echo "hello from custom cli"
          EOF
          chmod +x "$HOME/.local/bin/hello-cli"
          echo "$HOME/.local/bin" >> "$ATOMGIT_PATH"

      - name: Use custom cli
        run: |
          hello-cli

使用案例：将仓库脚本目录加入 PATH

steps:
  - uses: actions/checkout@v4

  - name: Add scripts to PATH
    run: |
      echo "$ATOMGIT_WORKSPACE/scripts/bin" >> "$ATOMGIT_PATH"

  - name: Run project script
    run: |
      project-build

5. ATOMGIT_STEP_SUMMARY：生成 Job Summary 页面摘要

用途

ATOMGIT_STEP_SUMMARY 用于写入 Markdown 内容，最终展示在流水线运行的 summary 页面。它适合展示测试摘要、构建结果、部署结果、质量门禁结果等关键信息，避免用户必须进入日志中查找重要结论。

每个 step 的 ATOMGIT_STEP_SUMMARY 文件彼此独立，job 结束后会汇总展示。

使用场景

适合面向用户展示“流水线执行结论”。

场景	示例
测试结果摘要	通过率、失败用例数、报告链接
构建结果摘要	版本号、产物名、镜像 tag
部署摘要	环境、服务地址、部署状态
质量门禁摘要	覆盖率、扫描结果、阻塞项
变更摘要	本次提交影响模块、PR 变更范围

使用案例：生成测试摘要

name: summary-example

on:
  push:

jobs:
  test:
    name: 测试
    runs-on: ubuntu-latest
    steps:
      - name: Generate test summary
        run: |
          echo "## Test Summary" >> "$ATOMGIT_STEP_SUMMARY"
          echo "" >> "$ATOMGIT_STEP_SUMMARY"
          echo "| Metric | Value |" >> "$ATOMGIT_STEP_SUMMARY"
          echo "|---|---:|" >> "$ATOMGIT_STEP_SUMMARY"
          echo "| Total | 128 |" >> "$ATOMGIT_STEP_SUMMARY"
          echo "| Passed | 126 |" >> "$ATOMGIT_STEP_SUMMARY"
          echo "| Failed | 2 |" >> "$ATOMGIT_STEP_SUMMARY"

使用案例：失败时覆盖摘要内容

steps:
  - name: Generate summary
    run: |
      echo "## Build Summary" >> "$ATOMGIT_STEP_SUMMARY"
      echo "Build is running..." >> "$ATOMGIT_STEP_SUMMARY"

      echo "## Build Summary" > "$ATOMGIT_STEP_SUMMARY"
      echo "Build failed. Please check logs." >> "$ATOMGIT_STEP_SUMMARY"

对于 summary，>> 表示追加内容，> 表示覆盖当前 step 已写入的内容；如果要完全删除当前 step 的 summary，可以删除 ATOMGIT_STEP_SUMMARY 指向的文件。Step 完成后，summary 会被上传，后续 step 不能再修改之前 step 已上传的 summary。

6. 选择建议

需求	推荐变量
后续 step 需要读取一个环境变量	ATOMGIT_ENV
后续 step 需要读取当前 step 的结构化输出	ATOMGIT_OUTPUT
下游 job 需要读取上游 job 的结果	ATOMGIT_OUTPUT + jobs.<job_id>.outputs
后续 step 需要直接调用新安装的 CLI	ATOMGIT_PATH
希望在 workflow 页面展示执行摘要	ATOMGIT_STEP_SUMMARY

7. 常见注意事项

7.1 当前 step 写入，通常后续 step 生效

ATOMGIT_ENV 和 ATOMGIT_PATH 写入后，当前 step 通常不能立即读取新值或新 PATH，后续 step 才能使用。设计流水线时，应把“写入”和“使用”拆成两个 step。

7.2 写入格式必须是追加到文件

典型写法是：

echo "NAME=value" >> "$ATOMGIT_ENV"
echo "name=value" >> "$ATOMGIT_OUTPUT"
echo "$HOME/.local/bin" >> "$ATOMGIT_PATH"
echo "## Summary" >> "$ATOMGIT_STEP_SUMMARY"

不要只执行 echo "NAME=value"，否则只是打印日志，不会被 runner 解析为环境文件命令。

7.3 多行内容要使用 delimiter

ATOMGIT_ENV 和 ATOMGIT_OUTPUT 都可以使用类似下面的多行格式：

{
  echo 'content<<EOF'
  echo 'line 1'
  echo 'line 2'
  echo EOF
} >> "$ATOMGIT_OUTPUT"

如果内容中可能出现独立一行的 EOF，应换成更随机的 delimiter，或者将内容写入普通文件，再传递文件路径。

7.4 不要覆盖平台默认变量

不要尝试通过 ATOMGIT_ENV 覆盖 ATOMGIT_* 或 RUNNER_* 默认变量。默认变量由平台设置，覆盖行为会被忽略或不受保证。

7.5 不要把敏感信息写入 summary 或日志

ATOMGIT_STEP_SUMMARY 展示在流水线运行 summary 页面，比日志更容易被用户看到。不要把 token、secret、账号密码、临时凭据写入 summary。即使平台具备敏感信息脱敏能力，也不应依赖脱敏机制作为安全边界。

8. 快速示例：一次性演示常用过程文件

name: atomgit-process-files-demo

on:
  workflow_dispatch:

jobs:
  demo:
    name: 示例
    runs-on: default
    steps:
      - name: Set env
        run: |
          echo "APP_ENV=dev" >> "$ATOMGIT_ENV"

      - name: Set output
        id: meta
        run: |
          echo "image_tag=demo-${ATOMGIT_RUN_NUMBER}" >> "$ATOMGIT_OUTPUT"

      - name: Add path
        run: |
          mkdir -p "$HOME/.local/bin"
          echo '#!/usr/bin/env bash' > "$HOME/.local/bin/demo-cli"
          echo 'echo demo cli works' >> "$HOME/.local/bin/demo-cli"
          chmod +x "$HOME/.local/bin/demo-cli"
          echo "$HOME/.local/bin" >> "$ATOMGIT_PATH"

      - name: Use env, output and path
        run: |
          echo "APP_ENV=$APP_ENV"
          echo "image_tag=${{ steps.meta.outputs.image_tag }}"
          demo-cli

      - name: Generate summary
        run: |
          echo "## Workflow Summary" >> "$ATOMGIT_STEP_SUMMARY"
          echo "" >> "$ATOMGIT_STEP_SUMMARY"
          echo "- Environment: $APP_ENV" >> "$ATOMGIT_STEP_SUMMARY"
          echo "- Image Tag: ${{ steps.meta.outputs.image_tag }}" >> "$ATOMGIT_STEP_SUMMARY"