wait-on-check-action

The check-name used in this action corresponds to the name of the job in your workflow.

1. Explicit Name: If you define name: My Job, the check name is My Job.
2. Job ID: If no name is defined, the check name defaults to the job ID.
3. Matrix Jobs: For matrix strategies, the check name includes the matrix values, e.g., Run tests (3.9).
4. Reusable Workflows: In a reusable workflow, the check name is formatted as caller-job-name / callee-job-name.

You can inspect the exact check names for a commit using the GitHub API:

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

To use this action, you need two workflows: one that performs the work (e.g., running tests) and another that waits for that work to complete before proceeding (e.g., publishing a package).

Workflow A (The Worker):

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

Workflow B (The Waiter):

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.0
        with:
          ref: ${{ github.ref }}
          check-name: "Run tests"
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          wait-interval: 10

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

If the checks you are waiting for are created by jobs that depend on other jobs (using needs), they might not exist immediately. Use checks-discovery-timeout to increase the window the action waits for these checks to appear in the GitHub API.

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

By default, the action fails if no checks match the provided check-name or check-regexp. If you are waiting for checks that only run under certain conditions (e.g., based on file changes), set fail-on-no-checks: false to allow the workflow to continue even if no matching checks are found.

- name: Wait on optional tests
  uses: lewagon/wait-on-check-action@v1.9.0
  with:
    ref: ${{ github.sha }}
    repo-token: ${{ secrets.GITHUB_TOKEN }}
    running-workflow-name: wait-for-optional-checks
    check-regexp: optional-.*
    fail-on-no-checks: false

If you are unsure how to configure the action, you can inspect the sample workflows located in the .github/workflows directory of the repository.

Key examples include:

• wait_omitting-check-name: Demonstrates how to wait for multiple tasks while omitting specific check names.
• wait_using_check-name: Demonstrates how to wait for one specific task.

Use check-regexp to wait for a group of checks that follow a specific naming convention (e.g., all test jobs in a matrix).

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

If you are using GitHub Enterprise, you must provide your custom API endpoint using the api-endpoint input.

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

Some services publish multiple checks with the same name (e.g., different environments or retries). By default, the action only considers the most recent run. To ensure the action only proceeds when every check sharing that name has succeeded, set wait-for-duplicates: true.

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

To wait for all checks to pass on a ref while ensuring the current workflow doesn't wait for itself, use the running-workflow-name input. This is useful for coordinating multiple workflows that trigger on the same event.

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.0
        with:
          ref: ${{ github.ref }}
          running-workflow-name: "Publish the package"
          repo-token: ${{ secrets.GITHUB_TOKEN }}