Job Outputs

~9 min · outputs, jobs, communication

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Outputs that cross runner boundaries

Step outputs only flow within a job. To pass values between jobs (which run on separate runners), declare job outputs. The pattern:

A step inside the producer job writes to $GITHUB_OUTPUT.
The producer job's outputs: map exposes the step output as a job output.
Consumer jobs declare needs: the producer.
Consumer reads via needs.<producer>.outputs.<name>.

Common shape

A setup job that decides what to run, followed by jobs that branch on the decision: 'is this a release or a normal CI?', 'which platforms should we deploy to?'.

Limitations

Job outputs are strings only. Use JSON if you need structured values: write JSON, read with fromJSON.
Maximum 1 MB total per job's outputs.

Code

Setup job decides, downstream jobs read·yaml

jobs:
  setup:
    runs-on: ubuntu-latest
    outputs:
      kind: ${{ steps.classify.outputs.kind }}
      python_versions: ${{ steps.classify.outputs.python_versions }}
    steps:
      - uses: actions/checkout@v4
      - id: classify
        run: |
          if [[ $GITHUB_REF == refs/tags/v* ]]; then
            echo 'kind=release' >> $GITHUB_OUTPUT
            echo 'python_versions=["3.11","3.12"]' >> $GITHUB_OUTPUT
          else
            echo 'kind=ci' >> $GITHUB_OUTPUT
            echo 'python_versions=["3.12"]' >> $GITHUB_OUTPUT
          fi

  test:
    needs: setup
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python: ${{ fromJSON(needs.setup.outputs.python_versions) }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '${{ matrix.python }}' }
      - run: pytest -q

  release:
    needs: [setup, test]
    if: needs.setup.outputs.kind == 'release'
    runs-on: ubuntu-latest
    steps:
      - run: ./release.sh

External links

GitHub — Defining outputs for jobs

Exercise

Add a setup job to your workflow that classifies the run (CI / release / nightly) and exposes that as a job output. Use it to gate a downstream deploy job. Confirm different events produce different paths.