How to use with multiple workflow files?

[dkaszews]

I have my jobs split across multiple workflow files for organization:

1. actionlint.yaml with job actionlint
2. format.yaml with jobs flake8 and mypy
3. test.yaml with jobs unit-test and integration-test

I have created a third file required.yaml with following:

name: Required
on:
  workflow_dispatch:
  push:
    branches:
      - main
  pull_request:

jobs:
  required:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    if: always()
    needs:
      - actionlint
      - flake8
      - mypy
      - unit-test
      - integration-test
    steps:
      - uses: actions/checkout@v4
      - uses: re-actors/alls-green@release/v1
        with:
          jobs: ${{ toJSON(needs) }}

But the Required check gets skipped, while Actionlint fails with:

Error: .github/workflows/required.yaml:10:3: job "required" needs job "actionlint" which does not exist in this workflow [job-needs]

I understand this means the needs only works in the same workflow file, so how do I check others? Do I need to duplicate the required job in every file?

[dkaszews]

I just ended up duplicating the job in all workflow files, under the same name. Adding that name as a status check causes all of them to be required, no need to specify each workflow separately. Not pretty, but workable.

[webknjaz]

When integrating into CPython, I came up with an idea of modules — move the individual bits into files reusable-*.yml. Those files are only allowed to have a workflow_call: trigger. Then, the main workflow ties it all together and has normal triggers like pull_request and push. It also had a job that dynamically decides which jobs to skip under certain conditions — this was the main challenge this structure was intended to solve originally. However, over time it became my go-to approach everywhere since it makes for such a good structure.
With this, you'll have only one workflow to integrate alls-green into. The job matrices are defined in the main workflow and the reusable ones are limited to just a single job definition. They can also define some inputs/outputs.
I see this layout as the best practice and many ecosystems I'm involved in picked up said approach since.

[dkaszews]

@webknjaz I am having hard time visualising this, could you please share some example repo?

[webknjaz]

• CPython has the main high-level/"entry point" workflow build.yml
• it defines typical triggers https://github.com/python/cpython/blob/229ed3dd1f97b2f87629a240b90eddba5ded67bf/.github/workflows/build.yml#L3-L12
• has a change detection job that computes which other job types should be skipped https://github.com/python/cpython/blob/229ed3dd1f97b2f87629a240b90eddba5ded67bf/.github/workflows/build.yml#L31-L44 (its definition is in a reusable workflow — https://github.com/python/cpython/blob/229ed3dd1f97b2f87629a240b90eddba5ded67bf/.github/workflows/reusable-context.yml)
• more individual job matrices are on the top level https://github.com/python/cpython/blob/229ed3dd1f97b2f87629a240b90eddba5ded67bf/.github/workflows/build.yml#L194-L205
• individual test jobs are included/called as "modules" https://github.com/python/cpython/blob/229ed3dd1f97b2f87629a240b90eddba5ded67bf/.github/workflows/build.yml#L206-L209 (defined in reusable workflows like https://github.com/python/cpython/blob/229ed3dd1f97b2f87629a240b90eddba5ded67bf/.github/workflows/reusable-macos.yml)
• finally, there's a job that waits for everything in the main workflow https://github.com/python/cpython/blob/229ed3dd1f97b2f87629a240b90eddba5ded67bf/.github/workflows/build.yml#L676-L752
• individual "modules" are reusable workflows with exactly one job in them (so that the calling workflow could have a matrix where more context exists), their naming pattern is reusable-*.yml and they only contain the workflow_call trigger https://github.com/python/cpython/blob/229ed3dd1f97b2f87629a240b90eddba5ded67bf/.github/workflows/reusable-ubuntu.yml#L4

[dkaszews]

I just ended up duplicating the job in all workflow files, under the same name. Adding that name as a status check causes all of them to be required, no need to specify each workflow separately. Not pretty, but workable.

I no longer recommend this approach, as it has a fatal flaw: https://github.com/orgs/community/discussions/183360#discussioncomment-15393272

If you use this, you need to assign distinct names, or forgo needs and use GitHub API to poll for status of other jobs, it even works across workflows.

name: Pull
on:
  pull_request:

jobs:
  actionlint:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
      - uses: raven-actions/actionlint@v2

  required:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    permissions: { actions: read }
    steps:
      - uses: actions/github-script@v7
        with:
          script: |
            core.info('failed/completed/total:');
            while (true) {
                const ref = context.payload.after;
                const jobs = await github.paginate(
                    github.rest.checks.listForRef,
                    { ...context.repo, ref, per_page: 100 }
                );
                const others = jobs.filter(j => j.name !== context.job);
                const completed = others.filter(j => j.status === 'completed');
                const failed = completed.filter(j => j.conclusion[0] !== 's');

                core.info(`${failed.length}/${completed.length}/${others.length}`)
                if (failed.length) {
                    core.setFailed(`Failed: ${failed.map(j => j.name).join(', ')}`);
                    break;
                } else if (completed.length == others.length) {
                    break;
                }
                await new Promise((r) => setTimeout(r, 10 * 1000));
            }