Outputs as inputs — the typed contract between jobs

Jobs can declare outputs and pass them to dependents. The producer promises a name and a string; the consumer reads via needs.<job_id>.outputs.<name>. One graph, two contracts: ordering and data.

Declaring outputs

The producer declares outputs at job level:

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      version: ${ steps.set-version.outputs.version }
      digest: ${ steps.set-digest.outputs.digest }
    steps:
      - id: set-version
        run: echo "version=1.2.3" >> "$GITHUB_OUTPUT"
      - id: set-digest
        run: echo "digest=sha256:abc..." >> "$GITHUB_OUTPUT"

The outputs: block maps names to expressions that resolve at job-completion time.

Setting outputs from a step

The $GITHUB_OUTPUT file is the runtime:

echo "version=1.2.3" >> "$GITHUB_OUTPUT"
echo "digest=$(sha256sum package.tar | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"

The runner captures each line as a named output.

Consuming outputs

A dependent reads via needs.<job_id>.outputs.<name>:

jobs:
  deploy:
    runs-on: ubuntu-latest
    needs: [build]
    steps:
      - run: |
          echo "Deploying ${ needs.build.outputs.version }"
          echo "Digest ${ needs.build.outputs.digest }"

The dependent must list the producer in needs:.

The typed contract

Outputs are strings. No schema validation; contract by convention.

flowchart LR
    B["build"] -->|outputs.version| D["deploy"]
    B -->|outputs.digest| D

Edges carry ordering (needs:) and data (outputs.<name>).

Outputs versus artifacts

• Outputs: typed, ephemeral, scoped to one run.
• Artifacts: untyped, durable, retained for retention-days.

# Outputs
echo "version=1.2.3" >> "$GITHUB_OUTPUT"

# Artifacts
- uses: actions/upload-artifact@v4
  with:
    name: package
    path: dist/package.tar

Outputs for values; artifacts for files.

Production discipline

1. Declare every output the consumer needs.
2. Validate shape at consumer if it matters.
3. Artifacts for files; outputs for values.
4. Document the output contract.

Cross-course references

• Ansible for Production Sysadmins - Part XXXVII uses AWX survey fields.
• Linux for Production Sysadmins - Part XXX uses EnvironmentFile.

Quiz