Learn how to trigger GitHub Actions workflows in one repository from another repository. This guide provides step-by-step instructions to set up repository dispatch triggers and Personal Access Tokens.

Triggering GitHub Actions from a Different Repository

Background

At work, I’m working on a project that spans multiple GitHub repositories. I need to trigger a job in one repository from a different repository. Let’s assume we have two repositories: the-tests and the-app. Whenever I make a change to the-app (the “source”), I want to run a workflow in the-tests (the “target”).

Repository Dispatch

GitHub provides a repository_dispatch trigger to trigger a workflow. Add it to the-tests repository:

# .github/workflows/integration-tests.yaml
name: "Integration Tests"

on:
  repository_dispatch:
    types:
      - integration-tests

jobs:
  integration-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Integration Tests
        run: ./integration-tests.sh

You can add this to an existing workflow file:

# .github/workflows/main.yaml
on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
  repository_dispatch:
    types:
      - integration-tests
# ...

Triggering with curl

Use curl to trigger this workflow via the dispatches REST endpoint. Example:

curl -qs \
  --fail-with-body \
  -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/$TARGET_REPO_OWNER/$TARGET_REPO/dispatches \
  -d '{"event_type":"integration-tests"}'
  • $BEARER_TOKEN: Fine-grained Personal Access Token (PAT).
  • $TARGET_REPO_OWNER: Owner of the target repository.
  • $TARGET_REPO: Name of the target repository.

Personal Access Token

Generate a Fine-grained Personal Access Token:

  1. Click your profile picture in GitHub and select “Settings”.
  2. Click “Developer settings” at the bottom-left of the settings page.
  3. Click “Personal access tokens” / “Fine-grained tokens” on the left-hand side.
  4. Click “Generate new token”.
  5. Name it and give it a sensible description.
  6. Under “Repository access”, choose “Only select repositories” and select the target repository.
  7. Under “Repository permissions”, choose “Contents: Read and write”.
  8. Click “Generate token” and copy the token (starts with github_pat_).

Triggering from the Source Repository

Create a workflow in the-app to include the curl command:

# .github/workflows/trigger-integration-tests.yaml
name: "Trigger Integration Tests"

on:
  push:
    branches: ["main"]

jobs:
  trigger-integration-tests:
    name: "Trigger Integration Tests"
    runs-on: ubuntu-latest

    steps:
      - name: "Trigger Integration Tests"
        run: |
          target_repo=the-tests
          curl -qs \
            --fail-with-body \
            -L \
            -X POST \
            -H "Accept: application/vnd.github+json" \
            -H "Authorization: Bearer ${{ secrets.THE_TESTS_PAT }}" \
            -H "X-GitHub-Api-Version: 2022-11-28" \
            https://api.github.com/repos/$GITHUB_REPOSITORY_OWNER/$target_repo/dispatches \
            -d '{"event_type":"integration-tests"}'

Secrets

To store the Personal Access Token as a secret:

  1. In the-app repository, click “Settings”.
  2. Click “Secrets and variables” under “Security”.
  3. Click “Actions”.
  4. Click “New repository secret”.
  5. Name it THE_TESTS_PAT and paste the PAT from earlier.
  6. Click “Add secret”.

Conclusion

Now, any push to main in the-app should trigger the “Run Integration Tests” workflow in the-tests. You can extend this so that multiple repositories trigger the integration tests.

What’s Missing?

  • Triggering the-tests for pull requests against dependencies.
  • Triggering integration tests only if all actions in the-app succeed.

What’s Annoying?

  • Multiple dependencies require the triggering workflow in each.
  • Multiple pushes trigger multiple times without waiting for everything to quiet down.

References