Skip to main content

no-unknown-job-output-reference

Rule catalog ID: R037

Targeted pattern scopeโ€‹

GitHub Actions workflow YAML files that reference job outputs through needs.<job_id>.outputs.<output_name> or reusable workflow outputs through jobs.<job_id>.outputs.<output_name>.

What this rule reportsโ€‹

This rule reports output references that point at:

  • a job that does not exist
  • a job that is not listed in the current job's direct needs
  • an output name that is not declared under the referenced job's outputs

Why this rule existsโ€‹

GitHub only populates the needs context for direct dependencies, and reusable workflow outputs must be mapped from declared job outputs. Typos in job IDs, missing needs dependencies, or misspelled output names silently evaluate to empty strings at runtime and can break downstream deployment, release, or reporting logic.

โŒ Incorrectโ€‹

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      artifact-sha: ${{ steps.pkg.outputs.sha }}
    steps:
      - id: pkg
        run: echo "sha=abc123" >> "$GITHUB_OUTPUT"

  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: echo "${{ needs.build.outputs.artifact_sha }}"

โœ… Correctโ€‹

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      artifact-sha: ${{ steps.pkg.outputs.sha }}
    steps:
      - id: pkg
        run: echo "sha=abc123" >> "$GITHUB_OUTPUT"

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "${{ needs.build.outputs.artifact-sha }}"

Additional examplesโ€‹

For larger repositories, this rule is often enabled together with one of the published presets so violations are caught in pull requests before workflow changes are merged.

ESLint flat config exampleโ€‹

import githubActions from "eslint-plugin-github-actions-2";

export default [
  {
    files: ["**/*.{yml,yaml}"],
    plugins: {
      "github-actions": githubActions,
    },
    rules: {
      "github-actions/no-unknown-job-output-reference": "error",
    },
  },
];

When not to use itโ€‹

You can disable this rule when its policy does not match your repository standards, or when equivalent enforcement is already handled by another policy tool.

Further readingโ€‹