Triggering Workflows in Another Repository with GitHub Actions

GitHub Actions provides a powerful automation framework that allows you to orchestrate and automate various tasks within your repositories. One of its features is the ability to trigger workflows in one repository from another repository. This can be useful for managing cross-repository actions, such as updating dependencies or deploying services.

In this guide, we will walk you through the steps to create a workflow in a source repository that triggers a workflow in a target repository.

Prerequisites

Before you begin, ensure you have the following:

• Access to the source repository (the repository where you want to trigger the workflow).
• Access to the target repository (the repository where the triggered workflow will run).
• Basic knowledge of GitHub Actions.

Step 1: Configure the Source Repository

1.1. Set Up the Trigger Workflow

In the source repository, create a new GitHub Actions workflow file or use an existing one. This file should define the workflow responsible for triggering the target workflow.

Example workflow file (trigger_workflow.yml):

name: Trigger Target Workflow

on:
  workflow_dispatch:
    inputs:
      target_service:
        description: 'Input a service name (e.g., demo-app)'
        required: true
      target_version:
        description: 'Input a version (e.g., v1.0.0)'
        required: true

jobs:
  trigger:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Workflow in Another Repository
        run: |
          repo_owner="REPOSITORY OWNER"
          repo_name="REPOSITORY NAME"
          event_type="trigger-workflow"
          service=${{ github.event.inputs.target_service }}
          version=${{ github.event.inputs.target_version }}

          curl -L \
            -X POST \
            -H "Accept: application/vnd.github+json" \
            -H "Authorization: Bearer ${{ secrets.PAT }}" \
            -H "X-GitHub-Api-Version: 2022-11-28" \
            https://api.github.com/repos/$repo_owner/$repo_name/dispatches \
            -d "{\"event_type\": \"$event_type\", \"client_payload\": {\"service\": \"$service\", \"version\": \"$version\"}}"

1.2. Configure the Trigger Logic

Inside your source workflow, define the logic and inputs required to trigger the target workflow.

• on: workflow_dispatch: This allows manual triggering of the workflow.
• Inputs: Users provide target_service (e.g., demo-app) and target_version (e.g., v1.0.0).
• Trigger Workflow Step:
  • Uses curl to send a POST request to GitHub API.
  • Requires a Personal Access Token (PAT) stored as a secret (secrets.PAT).

1.3. Commit and Push

Commit the changes to your source repository and push them to the main branch.

Step 2: Configure the Target Repository

2.1. Set Up the Target Workflow

In the target repository, create a new GitHub Actions workflow file.

Example workflow file (target_workflow.yml):

name: My Target Workflow

on:
  repository_dispatch:
    types: [trigger-workflow]
    
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.client_payload.sha }}

      - name: Extract Service Name & Version
        run: |
          service_name=${{ github.event.client_payload.service }}
          version=${{ github.event.client_payload.version }}
          echo "Service: $service_name, Version: $version"

2.2. Configure the Workflow Logic

• on: repository_dispatch: This allows the workflow to be triggered externally.
• Checkout Code:
  • Uses actions/checkout@v4.
  • Checks out the specific commit or branch referenced in client_payload.sha.
• Extract Service Name & Version:
  • Retrieves values from client_payload.
  • Displays them using echo.

2.3. Commit and Push

Commit the changes to your target repository and push them to the main branch.

Step 3: Trigger the Workflow

3.1. Manual Trigger

1. In the source repository, go to the “Actions” tab.
2. Select the “Trigger Target Workflow” workflow.
3. Click “Run workflow”.
4. Enter target_service and target_version values.
5. Click “Run workflow” to trigger the target workflow.

3.2. Automated Trigger (Optional)

You can automate this trigger by scheduling the source workflow or linking it to events like code pushes or pull requests.

Conclusion

You’ve successfully configured a GitHub Actions workflow in one repository to trigger another workflow in a different repository. This improves automation and streamlines cross-repository collaboration.

References

• Events that Trigger Workflows
• GitHub App Webhooks
• GitHub Actions Documentation