Wait On Check Action

Pause until a job in another workflow completes successfully.

This action uses GitHub's Checks API to poll for check results. On success, the action exits allowing the workflow to resume. Otherwise, the action exits with status code 1 and fails the workflow.

[!TIP] Prefer to skip the Ruby setup overhead? wait-on-check-action-ts is a TypeScript port that runs as a native node24 action with no setup step, while keeping the same parameters, defaults, and behavior.

When to use this action

• You need to wait for checks on non-default branches (PRs, feature branches)
• You need multiple workflows to wait atomically until all checks pass
• You need flexible check filtering (regex patterns, specific names, exclusions)
• You're coordinating workflows triggered by repository_dispatch or external events

Consider native GitHub Actions features when

• All your jobs are in the same workflow → use needs
• You only work on the default branch and simple triggers suffice → use workflow_run

Quickstart

Workflow A - Runs tests

name: Test

on: [push]

jobs:
  test:
    name: Run tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

Workflow B - Waits for tests before publishing

name: Publish

on: [push]

jobs:
  publish:
    name: Publish the package
    runs-on: ubuntu-latest
    steps:
      - name: Wait for tests to succeed
        uses: lewagon/wait-on-check-action@v1.9.1
        with:
          ref: ${{ github.ref }}
          check-name: "Run tests"
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          wait-interval: 10

      - uses: actions/checkout@v4
      - run: npm publish

Inputs

Required inputs

Optional inputs

Usage examples

Wait for a specific check

- name: Wait for tests
  uses: lewagon/wait-on-check-action@v1.9.1
  with:
    ref: ${{ github.ref }}
    check-name: "Run tests"
    repo-token: ${{ secrets.GITHUB_TOKEN }}

Wait for all checks (except current workflow)

jobs:
  publish:
    name: Publish the package
    runs-on: ubuntu-latest
    steps:
      - name: Wait for other checks to succeed
        uses: lewagon/wait-on-check-action@v1.9.1
        with:
          ref: ${{ github.ref }}
          running-workflow-name: "Publish the package"
          repo-token: ${{ secrets.GITHUB_TOKEN }}

Wait for checks matching a pattern

- name: Wait for all test jobs
  uses: lewagon/wait-on-check-action@v1.9.1
  with:
    ref: ${{ github.sha }}
    check-regexp: "test-.*"
    repo-token: ${{ secrets.GITHUB_TOKEN }}

Accept cancelled checks

- name: Wait for checks (allow cancelled)
  uses: lewagon/wait-on-check-action@v1.9.1
  with:
    ref: ${{ github.ref }}
    check-name: "Run tests"
    repo-token: ${{ secrets.GITHUB_TOKEN }}
    allowed-conclusions: success,skipped,cancelled

Ignore specific checks

- name: Wait for checks (ignore some)
  uses: lewagon/wait-on-check-action@v1.9.1
  with:
    ref: ${{ github.sha }}
    running-workflow-name: "Deploy"
    ignore-checks: "optional-lint,coverage-report"
    repo-token: ${{ secrets.GITHUB_TOKEN }}

Allow no matching checks

By default, if you use check-name or check-regexp and no checks match the filter, the action will fail with the message "The requested check was never run against this ref, exiting...".

If you want the action to succeed when no checks match the filter (useful for conditional workflows where certain checks only run on specific file changes), you can set fail-on-no-checks to false:

name: Wait for optional checks
on:
  push:
jobs:
  wait-for-optional-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Wait on optional tests
        uses: lewagon/wait-on-check-action@v1.9.1
        with:
          ref: ${{ github.sha }}
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          running-workflow-name: wait-for-optional-checks
          check-regexp: optional-.*
          fail-on-no-checks: false

Wait for a check that doesn't exist yet

When a job uses needs it isn't created until the dependent jobs are completed.

If you want to extend the discovery time window to wait for jobs to be created, you can set checks-discovery-timeout:

jobs:
  setup:
    # Some slow setup job
  test:
    needs: setup
    name: Run Tests

- name: Wait for tests
  uses: lewagon/wait-on-check-action@v1.9.1
  with:
    ref: ${{ github.ref }}
    check-name: "Run tests"
    repo-token: ${{ secrets.GITHUB_TOKEN }}
    checks-discovery-timeout: 300

Wait for services that publish duplicate check names

Some services publish multiple check_runs under the same name on a single commit — one per environment, retry, or internal worker. By default only the most recent run for a given name is considered, so when these runs finish at different times the first one to complete determines the reported status. A single early failure can then fail the wait even though a later run of the same name succeeds, making the result non-deterministic from one CI run to the next.

Set wait-for-duplicates: true to require every check sharing a name to succeed before the action continues:

- name: Wait for deploy preview
  uses: lewagon/wait-on-check-action@v1.9.1
  with:
    ref: ${{ github.ref }}
    check-name: "Deploy Preview"
    repo-token: ${{ secrets.GITHUB_TOKEN }}
    wait-for-duplicates: true

Understanding check names

The check name corresponds to jobs.<job_id>.name in your workflow:

# Check name: "test" (uses job ID)
jobs:
  test:
    runs-on: ubuntu-latest
    steps: [...]

# Check name: "Run tests" (uses explicit name)
jobs:
  test:
    name: Run tests
    runs-on: ubuntu-latest
    steps: [...]

# Check names: "Run tests (3.9)", "Run tests (3.10)", etc.
jobs:
  test:
    name: Run tests
    strategy:
      matrix:
        python: ['3.9', '3.10', '3.11']

To inspect check names via the API:

curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/commits/REF/check-runs \
  | jq '[.check_runs[].name]'

Reusable workflows

When using this action in a reusable workflow, the check name includes both the caller and callee job names:

.github/workflows/caller.yml

on: push
jobs:
  caller:
    uses: ./.github/workflows/callee.yml

.github/workflows/callee.yml

on: workflow_call
jobs:
  callee:
    runs-on: ubuntu-latest
    steps:
      - name: Wait for other workflows
        uses: lewagon/wait-on-check-action@v1.9.1
        with:
          ref: ${{ github.ref }}
          running-workflow-name: "caller / callee"
          repo-token: ${{ secrets.GITHUB_TOKEN }}

GitHub Enterprise support

Pass your GHE API endpoint:

- name: Wait for tests (GHE)
  uses: lewagon/wait-on-check-action@v1.9.1
  with:
    ref: ${{ github.ref }}
    check-name: "Run tests"
    repo-token: ${{ secrets.GITHUB_TOKEN }}
    api-endpoint: https://github.mycompany.com/api/v3

Known limitations

• Pagination: The action handles up to 100 concurrent workflow runs. If you have more, some may not be detected.
• API Rate Limits: Frequent polling may hit GitHub API rate limits. Increase wait-interval if needed.

Alternatives

Using needs

For jobs in the same workflow, use the native needs keyword:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test

  deploy:
    needs: test # Waits for test to complete successfully
    runs-on: ubuntu-latest
    steps:
      - run: npm run deploy

Using workflow_run

For triggering workflows on the default branch after another workflow completes:

name: Deploy

on:
  workflow_run:
    workflows: ["Test"]
    types: [completed]

jobs:
  deploy:
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - run: npm run deploy

Limitations of workflow_run:

• Only triggers on the default branch
• Triggers once per workflow completion (not atomic "wait for all")
• Requires manual success checking with if condition

Development

Dependencies

To install dependencies:

bundle install

Some packages must be installed from npm and PyPI:

npm install cspell husky prettier
pip install bump2version trufflehog3

Tests

To run tests:

bundle exec rspec

There are sample workflows in the .github/workflows directory that demonstrate the action. The wait_omitting-check-name workflow waits for two simple tasks, while wait_using_check-name only waits for a specific task.

Documentation

To generate the documentation locally:

bundle exec yard

Linters

To run linters:

npx cspell . --dot --gitignore
bundle exec rubocop
trufflehog3 --no-history

Formatters

To run formatters:

prettier . --write

Contributing

Please read our Code of Conduct and Changelog before contributing.

This repository uses semantic versioning.

bump2version is used to version and tag changes, for example:

bump2version patch  # 1.4.1 → 1.4.2
bump2version minor  # 1.4.1 → 1.5.0
bump2version major  # 1.4.1 → 2.0.0

License

See the LICENSE file.