任务间传递输出参数

本文档介绍 AtomGit Action 的 Step → Job → Workflow 三级输出传递模型，支持跨步骤和跨任务共享数据。

当你需要在 step 之间、job 之间、甚至 workflow 之间传递输出参数时，例如将构建版本号从 build job 传递给 deploy job。

前提条件

• 理解 id、outputs、needs 的作用。
• 理解 ATOMGIT_OUTPUT 环境变量的用法。

快速示例

name: pipeline-with-outputs

on:
  push:
    branches:
      - main

jobs:
  prepare:
    name: 准备
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - name: Run output version
      	id: version
        run: echo "version=1.0.0" >> "$ATOMGIT_OUTPUT"
      - name: Run output sha
      	id: sha
        run: echo "sha=${{ atomgit.sha }}" >> "$ATOMGIT_OUTPUT"

  build:
    name: 构建
    runs-on: [ubuntu-latest, x64, small]
    needs: prepare
    steps:
      - name: Use output from prepare
        run: |
          echo "version=${{ jobs.prepare.outputs.version }}"
          echo "sha=${{ jobs.prepare.outputs.sha }}"

配置说明

三级传递模型

AtomGit Action 支持 outputs 的三级传递：Step → Job → Workflow

Step 输出（ATOMGIT_OUTPUT）
  → 映射到 Job 输出（jobs.<job_id>.outputs）
    → 映射到 Workflow_call job 输出（jobs.workflow_call_job_id.outputs）

Step 输出

在 step 中使用 ATOMGIT_OUTPUT 环境变量写入输出：

steps:
  - name: Run output 
  	id: version
    run: echo "version=1.0.0" >> "$ATOMGIT_OUTPUT"

  - name: Run build 
  	id: build-result
    run: |
      echo "status=success" >> "$ATOMGIT_OUTPUT"
      echo "artifact-path=dist/app.tar.gz" >> "$ATOMGIT_OUTPUT"

  - name: Use step output
    run: echo "version=${{ steps.version.outputs.version }}"

注意：每个输出参数的值最大不超过 1MB。多行输出需使用分隔符语法。

Job 输出

将 step 输出映射到 job 输出，使其他 job 通过 needs 引用：

jobs:
  prepare:
    name: 准备
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - name: Run output 
      	id: version
        run: echo "version=1.0.0" >> "$ATOMGIT_OUTPUT"
      - name: Run build
      	id: build-result
        run: echo "status=success" >> "$ATOMGIT_OUTPUT"

  deploy:
    runs-on: [ubuntu-latest, x64, small]
    needs: prepare
    steps:
      - name: Use job output
        run: |
          echo "version=${{ jobs.prepare.outputs.version }}"
          echo "status=${{ jobs.prepare.outputs.status }}"

Workflow 输出

在可重用工作流（workflow_call）中，可将 job 输出映射到 workflow 输出：

name: reusable-build

on:
  workflow_call:
    outputs:
      version:
        description: "构建版本号"
        value: ${{jobs.prepare.outputs.version}}

jobs:
  prepare:
    name: 准备
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - name: Run output 
      	id: version
        run: echo "version=1.0.0" >> "$ATOMGIT_OUTPUT"

调用方接收输出：

jobs:
  call-build:
    name: 调用构建
    uses: ./.gitcode/workflows/reusable-build.yml
  deploy:
    name: 部署
    needs: call-build
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - name: Use workflow output
        run: echo "version=${{ jobs.call-build.outputs.version }}"

多行输出

写入多行值到 ATOMGIT_OUTPUT 时使用分隔符语法：

steps:
  - name: Run output 
  	id: multiline-output
    run: |
      EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
      echo "content<<$EOF" >> "$ATOMGIT_OUTPUT"
      echo "line1" >> "$ATOMGIT_OUTPUT"
      echo "line2" >> "$ATOMGIT_OUTPUT"
      echo "$EOF" >> "$ATOMGIT_OUTPUT"