GitHub Actions Cross-Repo Workflow Dispatch

With rest actions from github, you are empowered to trigger workflows in other repositories. This is especially useful for platform teams who want to provide a self-service experience for their users, and handle the provisioning and maintenance of the underlying infrastructure separately. In the following example, we will set up a workflow in gha-example-self that dispatches a workflow in gha-example-infra when triggered.

The core logic that dispatches the workflow looks like this:

script: |
  github.rest.actions.createWorkflowDispatch({
    owner: context.repo.owner,
    repo: 'gha-example-infra',
    workflow_id: 'build-infra-dev.yml',
    ref: 'main',
  });

However, apart from some boilerplate, we are missing the app-token step, which is responsible for generating a token with the necessary permissions to dispatch workflows in the target repository. To set this up, we need to create a GitHub App and generate a private key.

Make a Github App

Step 1: Create a GitHub App Go to GitHub App settings:

Navigate to GitHub App Settings Or: GitHub → Settings → Developer settings → GitHub Apps Click "New GitHub App" Fill out the basic information:

GitHub App name: "Workflow Dispatcher" (or any name you prefer) Homepage URL: https://github.com/aukoyy/gha-example-self

Configure permissions: Under Repository permissions, set:

Actions: Read and Write (to dispatch workflows) Contents: Read (basic access) Metadata: Read (required baseline permission) Set installation scope: Select "Only on this account" Or "Any account" if you need broader access Create the app:

Click "Create GitHub App"

If prompted for a WebHook URL, notice that you can uncheck "Active" and then you will be allowed to leave it blank.

Step 2: Get your App ID

After creating the app:

You'll see App ID on the app's settings page Copy this number (e.g., 123456)

Step 3: Generate a Private Key

On your app's settings page:

Scroll down to "Private keys" Click "Generate a private key" A .pem file will download to your computer Prepare the private key:

Open the .pem file in a text editor like vim or VS Code Copy the entire contents (including -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----)

Step 4: Install the App

Install to your repositories: Go to your app's settings page Click "Install App" in the left sidebar Choose your account (aukoyy) Select "Selected repositories" and choose: gha-example-self (your current repo) gha-example-infra (the target repo)

Step 5: Add Secrets to Your Repository

Go to your repository settings:

Navigate to Repository Secrets Settings Or: Your repo → Settings → Secrets and variables → Actions Add the secrets:

Secret 1: APP_ID

Name: APP_ID Value: The app ID number (e.g., 123456) Secret 2: APP_PRIVATE_KEY

Name: APP_PRIVATE_KEY Value: The entire contents of your .pem file

Bringing it all together

Now we can add the app token step to our workflow and see it in action:

name: dispatch-infra-dev

on:
  workflow_dispatch:
  push:

jobs:
  dispatch-remote:
    runs-on: ubuntu-latest
    steps:
      - name: Generate app token
        id: app-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
          owner: ${{ github.repository_owner }}
          repositories: gha-example-infra
      - name: dispatch build
        uses: actions/github-script@v7
        with:
          github-token: ${{ steps.app-token.outputs.token }}
          script: |
            console.log('Dispatching remote workflow')
            github.rest.actions.createWorkflowDispatch({
              owner: context.repo.owner,
              repo: 'gha-example-infra',
              workflow_id: 'build-infra-dev.yml',
              ref: 'main',
            });

Code used in this example

Feel free to copy the full workflow and test it out yourself! You can trigger the workflow from the Actions tab in GitHub, and you should see it dispatch the workflow in gha-example-infra successfully.

Bonus: read files from the self service repo

asdf