`jobs` context isn't listed as a context in the Contexts article

[jsoref]

Code of Conduct

• [X] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/actions/learn-github-actions/contexts

What part(s) of the article would you like to see updated?

Add a

Jobs context

Insert text explaining its structure. It's probably just a jobs.job-id.job-context-content but maybe it isn't?

There should be a reminder that the job-id is just the label for the item under jobs: in the yaml -- it comes up periodically that people expect:

jobs:
  something:
    id: an-id

Additional information

Workflow key	Context	Special functions
concurrency	github, inputs
jobs.<job_id>.steps.working-directory	github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs	hashFiles
on.workflow_call.outputs.<output_id>.value	github, jobs [this is not defined as a context on this page], inputs

[steveward]

Thanks @jsoref! I'll mark this for someone to review to confirm.

[github-actions[bot]]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert :eyes:

[ChristopherHX]

Not a typo..., but unclear / incomplete documentation

on:
  workflow_call:
    outputs:
      A:
        value: ${{ jobs.my_job.outputs.A }} # jobs is equivalent to the needs context and has the same structure, but includes all jobs in the current workflow file
jobs:
  my_job:
    outputs:
      A: MyOutput
    runs-on: ubuntu-latest
    steps:
    - run: exit 0

[jsoref]

Indeed, so, it isn't that it's a typo, it's that the jobs context isn't listed on this page at all.

Obviously, it should be.

I'll change the issue description ~after we get confirmation...~

[github-actions[bot]]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[github-actions[bot]]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[github-actions[bot]]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[github-actions[bot]]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[github-actions[bot]]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[github-actions[bot]]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[lucascosti]

👋 Thanks for opening this issue!

🤔 Yes, this is a bit complicated. For regular workflows, there is no jobs context. The jobs context only applies to reusable workflows (i.e. workflows with an on.workflow_call trigger), but I'm not 100% sure on where it can be used or what's in it; it might only be available to set workflow outputs in the called workflow. I'll have to check in with engineering.

[ajaykn]

@lucascosti Thats right, this is available for reusable workflows while setting the output values.

Something like this:

 workflow_call:
    outputs:
      output1:
        value: ${{ toJSON(jobs.job1) }}
      output2:
        value: ${{ toJSON(jobs.job2) }}

and output1 data can look like:

{
  result: success,
  outputs: {
    output1: hello2,
    output2: world2
  }
}

[jsoref]

@lucascosti, technically the document already warns users about this: https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability

Different contexts are available throughout a workflow run. For example, the secrets context may only be used at certain places within a job.

In addition, some functions may only be used in certain places. For example, the hashFiles function is not available everywhere.

Now, it's probably true that this text is way too far down the document.

I'd argue that the structure should be:

1. About contexts (the stuff before the pink box in https://docs.github.com/en/actions/learn-github-actions/contexts#about-contexts)
2. Availability disclaimer (https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)
3. List of contexts -- with its own anchor so I can link to it (the stuff after the pink box in https://docs.github.com/en/actions/learn-github-actions/contexts#about-contexts)

I don't have a particular opinion about where to put the pink box.

It sounds like the description of the jobs context is:

jobs context

The jobs context provides information about other jobs in the workflow.

Property name	Type	Description
<job_id>.result	string	The result of the job.
<job_id>.outputs	object	The set of outputs defined for the job. For more information, see "Metadata syntax for GitHub Actions."