Cross-Repository Workflows: Connecting Microservices with GitHub Actions

Previously in this course, we explored automating releases and managing complex pipeline configurations. In this lesson, we move beyond the single-repository mindset to coordinate microservices through integration and decoupled workflows.

In a real-world microservices architecture, changes in one service often require downstream actions in another. For example, when your "Auth Service" updates its API schema, your "Gateway Service" might need to run integration tests against the new contract. We achieve this loose coupling using repository_dispatch events.

The Concept: Repository Dispatch Explained

A repository_dispatch is a webhook-based trigger that allows an external system (or another GitHub Action) to fire a custom event in a target repository.

Think of it as a signal:

1. Repository A (The Producer): Completes a job and sends an HTTP POST request to the GitHub API.
2. GitHub API: Receives the request and looks for a repository configured to listen for that specific event name.
3. Repository B (The Consumer): Detects the event and triggers a workflow.

This approach is superior to hard-coding dependencies because the services remain independent. Repository B doesn't need to know who triggered it; it only needs to know how to respond to the signal.

Implementation: Triggering Downstream Workflows

To implement this, you need two parts: the sender (the trigger) and the receiver (the listener).

1. The Receiver (Target Repository)

In your downstream repository (e.g., api-gateway), you configure the workflow to listen for a repository_dispatch event.

YAML
# .github/workflows/downstream-task.yml
name: Downstream Integration
on:
  repository_dispatch:
    types: [service-updated]

jobs:
  run-integration-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Run tests
        run: echo "Service updated, running integration tests against new version ${{ github.event.client_payload.version }}"

2. The Sender (Source Repository)

In your upstream repository, you use a curl command or an action to send the event. You will need a GitHub Personal Access Token (PAT) stored as a secret in this repository.

YAML
# .github/workflows/upstream-trigger.yml
name: Notify Downstream
on:
  push:
    branches: [main]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Downstream
        env:
          TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}
        run: |
          curl -X POST https://api.github.com/repos/my-org/api-gateway/dispatches \
          -H "Accept: application/vnd.github.v3+json" \
          -H "Authorization: token $TOKEN" \
          -d '{"event_type": "service-updated", "client_payload": {"version": "1.0.2"}}'

Hands-on Exercise

1. Create a Personal Access Token in your GitHub settings with repo scope.
2. Add this token as a secret named REPO_ACCESS_TOKEN in your source repository.
3. Set up the "Receiver" workflow in a separate repository (or a different folder).
4. Push a change to your source repository and verify in the GitHub Actions UI of the receiver repository that the workflow was triggered.

Common Pitfalls

• Missing Permissions: The GITHUB_TOKEN provided by default in a workflow cannot trigger events in other repositories. You must use a personal access token (PAT) or a GitHub App token.
• Event Mismatch: Ensure the types in the receiver exactly match the event_type sent in the JSON payload.
• Infinite Loops: If Repository A triggers Repository B, and B triggers A, you will create an infinite loop. Always ensure your triggers are directional and avoid circular dependencies.

Frequently Asked Questions

Q: Can I send data between repositories? Yes. The client_payload field allows you to send JSON data, such as build versions, environment names, or commit SHAs, which your target workflow can use.

Q: Is this the only way to link workflows? No. You can also use workflow_run triggers, which allow one workflow to trigger automatically when another specific workflow completes. repository_dispatch is more flexible for custom events.

Recap

We've successfully moved beyond single-repository automation by using repository_dispatch events. By decoupling our microservices, we ensure that our CI/CD pipelines can communicate across repository boundaries, enabling complex integration testing and cross-service deployment coordination.

Up next: We will discuss how to improve system reliability by configuring retries, timeouts, and handling transient errors in your pipelines.