DevOps Bootcamp · Lesson

Cross-Repository Workflows

Learn to chain workflows across different repositories to manage dependencies and orchestrate complex deployments.

Cross-Repository Workflows is a free DevOps Bootcamp lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the DevOps Bootcamp learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Introduction to Cross-Repository Workflows

In modern software development, applications often consist of multiple components spread across different repositories. Think microservices, shared libraries, or separate deployment configurations.

Orchestrating workflows across these distinct repositories allows for greater modularity and separation of concerns. This lesson explores how to achieve this with GitHub Actions.

Why Cross-Repo Orchestration?

Traditionally, GitHub Actions workflows are scoped to a single repository. But what if you need:

To build an artifact in one repo and trigger a deployment in another?
A shared configuration repository to trigger updates in multiple service repos?
To enforce security policies managed in a central repository across all others?

Cross-repository workflows provide the solution for these complex scenarios.

Connecting Repos: `repository_dispatch`

GitHub Actions offers a special event type called repository_dispatch. This acts like a custom webhook for your GitHub repositories.

One workflow (the 'sender') sends an API request to GitHub.
Another workflow (the 'receiver') in a different repository listens for this specific event.

This allows programmatic triggering of workflows across different repositories.

Setting Up the Receiver Workflow

To receive a repository_dispatch event, a workflow in the target repository needs to be configured to listen for it. This is done using the on: keyword.

Here's how a workflow in repo-B might look:

name: Receive Dispatch Event

on:
  repository_dispatch:
    types: [my-custom-event]

jobs:
  process-event:
    runs-on: ubuntu-latest
    steps:
      - name: Log event payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload: ${{ toJSON(github.event.client_payload) }}"

Understanding the Receiver Configuration

In the previous example:

on: repository_dispatch: tells GitHub to listen for this event.
types: [my-custom-event] specifies that this workflow will only run if the dispatched event has the my-custom-event type. You can define multiple types.
github.event.action will contain the event type (e.g., my-custom-event).
github.event.client_payload holds any custom data sent with the dispatch.

Triggering the Event: Sending from Another Repo

To trigger a repository_dispatch event, you need to make an HTTP POST request to the GitHub API. This can be done using curl or the GitHub CLI (gh cli) from within another GitHub Actions workflow or a script.

Key requirements:

The target repository's owner and name.
An event type that the receiver workflow is listening for.
A client_payload for any custom data.
A GitHub Personal Access Token (PAT) with repo scope.

Example: Dispatching with `gh cli`

Here's a workflow in repo-A that dispatches an event to repo-B. Notice how we use a secret for the token and pass a client_payload.

name: Trigger Deploy Workflow

on:
  push:
    branches: [main]

jobs:
  dispatch:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install GitHub CLI
        run: sudo apt-get update && sudo apt-get install gh -y

      - name: Dispatch event to repo-B
        env:
          GH_TOKEN: ${{ secrets.CROSS_REPO_PAT }}
        run: |
          gh api \
            --method POST \
            -H "Accept: application/vnd.github.v3+json" \
            /repos/YOUR_ORG/repo-B/dispatches \
            -f event_type='my-custom-event' \
            -f client_payload='{"ref":"${{ github.ref }}", "sha":"${{ github.sha }}"}'

Securing Cross-Repository Access

The default GITHUB_TOKEN provided to a workflow is limited to the repository where the workflow is running. To trigger events in *another* repository, you need a token with broader permissions.

Use a Personal Access Token (PAT) with repo scope.
Store this PAT as a repository secret (e.g., CROSS_REPO_PAT) in the triggering repository.
Never hardcode PATs directly in your workflow files.

Passing Custom Data with `client_payload`

The client_payload is a JSON object that you can include when dispatching an event. This is crucial for passing context or data from the triggering workflow to the receiving one.

Examples of data you might pass:

The commit SHA or branch name that triggered the build.
An environment target (e.g., "staging", "production").
A version number of an artifact to be deployed.

Remember: client_payload is visible in the workflow logs, so avoid sensitive information.

Quick Check on Cross-Repo Workflows

You've learned how to orchestrate workflows across different GitHub repositories. Let's test your understanding of the key components.

Recap: Orchestrating Across Repos

You've successfully learned how to implement cross-repository workflows using repository_dispatch!

Why: To manage dependencies and orchestrate complex deployments across multiple repositories.
How: A 'sender' workflow makes an API call to GitHub, triggering a 'receiver' workflow in another repo.
Key: The repository_dispatch event type and matching types in the receiving workflow.
Data: Use client_payload to pass non-sensitive information between workflows.
Security: Always use a PAT with repo scope, stored as a secret, for cross-repo access.

This powerful feature enables highly flexible and decoupled CI/CD pipelines.

Frequently asked questions

Is the “Cross-Repository Workflows” lesson free?

Yes — the full text of “Cross-Repository Workflows” is free to read here on the web, and the DevOps Bootcamp course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the DevOps Bootcamp course, upgrade to CoddyKit PRO.

What will I learn in “Cross-Repository Workflows”?

Learn to chain workflows across different repositories to manage dependencies and orchestrate complex deployments. You practise DevOps Bootcamp with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start DevOps Bootcamp?

No prior experience is required. DevOps Bootcamp on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Cross-Repository Workflows” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this DevOps Bootcamp lesson?

Yes. Every DevOps Bootcamp lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to DevOps Bootcamp