Cross-Repo Workflows — Trigger Actions Across Repositories

How Cross-Repo Triggering Works

Your website repos detect a push and send a signal to the central actions repo. The central repo runs the shared workflow, checking out the website code and deploying it.

3 Ways to Trigger Cross-Repo Workflows

Approach 1: repository_dispatch

The source repo (website) fires an API event to the target repo (central actions). The target repo listens for that event and runs a workflow.

Step 1: Create a PAT

Go to Settings → Developer settings → Personal access tokens → Fine-grained tokens and create a token with:

• Repository access: select the central actions repo
• Permissions: Contents (read), Metadata (read), Actions (write)

Add this token as a secret (DISPATCH_TOKEN) in each website repo under Settings → Secrets → Actions.

Step 2: Listener in the Central Repo

# central-actions-repo/.github/workflows/deploy-website.yml
name: Deploy Website

on:
  repository_dispatch:
    types: [deploy-website]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Show which site triggered this
        run: |
          echo "Repo: ${{ github.event.client_payload.repo }}"
          echo "Branch: ${{ github.event.client_payload.branch }}"
          echo "Commit: ${{ github.event.client_payload.sha }}"

      - name: Checkout the website repo
        uses: actions/checkout@v4
        with:
          repository: ${{ github.event.client_payload.repo }}
          ref: ${{ github.event.client_payload.sha }}
          token: ${{ secrets.WEBSITE_REPO_TOKEN }}

      - name: Build and deploy
        run: |
          echo "Building ${{ github.event.client_payload.repo }}..."
          # Your build & deploy commands here
          npm ci
          npm run build

Step 3: Trigger from Each Website Repo

# website-repo/.github/workflows/trigger-deploy.yml
name: Trigger Central Deploy

on:
  push:
    branches: [main]

jobs:
  trigger:
    runs-on: ubuntu-latest
    steps:
      - name: Dispatch to central actions repo
        run: |
          curl -X POST \
            -H "Accept: application/vnd.github+json" \
            -H "Authorization: Bearer ${{ secrets.DISPATCH_TOKEN }}" \
            https://api.github.com/repos/YOUR-ORG/central-actions/dispatches \
            -d '{
              "event_type": "deploy-website",
              "client_payload": {
                "repo": "${{ github.repository }}",
                "branch": "${{ github.ref_name }}",
                "sha": "${{ github.sha }}",
                "site_name": "my-website-1"
              }
            }'

Approach 2: workflow_dispatch via API

Similar to repository_dispatch, but you trigger a specific workflow file and can pass typed inputs (string, choice, boolean).

Listener in the Central Repo

# central-actions-repo/.github/workflows/deploy-website.yml
name: Deploy Website

on:
  workflow_dispatch:
    inputs:
      repo:
        description: 'Full repo name (org/repo)'
        required: true
        type: string
      ref:
        description: 'Git ref to deploy'
        required: true
        type: string
      environment:
        description: 'Target environment'
        required: true
        default: 'production'
        type: choice
        options:
          - staging
          - production

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - name: Checkout website code
        uses: actions/checkout@v4
        with:
          repository: ${{ inputs.repo }}
          ref: ${{ inputs.ref }}
          token: ${{ secrets.WEBSITE_REPO_TOKEN }}

      - name: Build and deploy
        run: |
          echo "Deploying ${{ inputs.repo }} to ${{ inputs.environment }}"
          npm ci && npm run build

Trigger via API from the Website Repo

# website-repo/.github/workflows/trigger-deploy.yml
name: Trigger Central Deploy

on:
  push:
    branches: [main]

jobs:
  trigger:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger workflow_dispatch via API
        run: |
          curl -X POST \
            -H "Accept: application/vnd.github+json" \
            -H "Authorization: Bearer ${{ secrets.DISPATCH_TOKEN }}" \
            https://api.github.com/repos/YOUR-ORG/central-actions/actions/workflows/deploy-website.yml/dispatches \
            -d '{
              "ref": "main",
              "inputs": {
                "repo": "${{ github.repository }}",
                "ref": "${{ github.sha }}",
                "environment": "production"
              }
            }'

Approach 3: Reusable Workflows (workflow_call)

Instead of the central repo listening for events, each website repo calls a reusable workflow defined in the central repo. The CI/CD logic lives centrally, but execution happens in the caller's context.

Reusable Workflow in the Central Repo

# central-actions-repo/.github/workflows/build-and-deploy.yml
name: Reusable Build & Deploy

on:
  workflow_call:
    inputs:
      node-version:
        description: 'Node.js version'
        required: false
        type: string
        default: '22'
      environment:
        description: 'Deploy target'
        required: true
        type: string
    secrets:
      CF_API_TOKEN:
        required: true
      CF_ACCOUNT_ID:
        required: true

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: 'npm'

      - run: npm ci
      - run: npm run build

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}
          accountId: ${{ secrets.CF_ACCOUNT_ID }}
          projectName: ${{ github.event.repository.name }}
          directory: dist

Caller in Each Website Repo

# website-repo/.github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    uses: YOUR-ORG/central-actions/.github/workflows/build-and-deploy.yml@main
    with:
      environment: production
      node-version: '22'
    secrets:
      CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
      CF_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}

Which Approach Should You Use?

Full Example: Your Multi-Website Setup

Here's the complete setup for your scenario: multiple website repos, one central private repo with shared deploy logic.

Repo Structure

# Your repos:
your-org/central-actions    # Private — contains reusable workflows
your-org/website-alpha      # Private — website 1
your-org/website-beta       # Private — website 2
your-org/website-gamma      # Private — website 3

Central Repo: Reusable Deploy Workflow

# central-actions/.github/workflows/deploy.yml
name: Reusable Deploy

on:
  workflow_call:
    inputs:
      build-command:
        description: 'Build command to run'
        type: string
        default: 'npm run build'
      output-dir:
        description: 'Build output directory'
        type: string
        default: 'dist'
      node-version:
        type: string
        default: '22'
    secrets:
      DEPLOY_TOKEN:
        required: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: 'npm'

      - run: npm ci
      - run: ${{ inputs.build-command }}

      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: ${{ inputs.output-dir }}

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download build artifact
        uses: actions/download-artifact@v4
        with:
          name: build-output
          path: ./deploy

      - name: Deploy
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          echo "Deploying ${{ github.event.repository.name }}..."
          # Replace with your actual deploy command:
          # e.g., rsync, scp, Cloudflare Wrangler, AWS S3 sync
          ls -la ./deploy

Each Website Repo: 3-Line Caller

# website-alpha/.github/workflows/deploy.yml
name: Deploy Website

on:
  push:
    branches: [main]

jobs:
  deploy:
    uses: your-org/central-actions/.github/workflows/deploy.yml@main
    with:
      build-command: 'npm run build'
      output-dir: 'dist'
    secrets:
      DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

That's it. Every website repo has the same tiny workflow file. All the build/deploy logic lives in central-actions. Update once, all sites get the change.

Token & Permissions Setup

Cross-repo access requires careful token configuration. Here's what each approach needs:

For repository_dispatch / workflow_dispatch

1. Create a Fine-grained PAT with access to the central repo (Contents: read, Actions: write)
2. Add the PAT as a secret (DISPATCH_TOKEN) in every website repo
3. The website repo's workflow uses this token to call the GitHub API

For reusable workflows (workflow_call)

1. In the central repo: Settings → Actions → General → Access → "Accessible from repositories in the organization"
2. No PAT needed for the call itself (org-level trust)
3. Secrets are passed explicitly from the caller — the central workflow never "sees" secrets it isn't given

For checking out cross-repo code (repository_dispatch approach)

1. The central repo needs a PAT (WEBSITE_REPO_TOKEN) that can read the website repos
2. Used in actions/checkout with the repository: and token: parameters

Debugging Cross-Repo Triggers

Cross-repo workflows fail silently more often than in-repo ones. Common pitfalls:

Verify a Dispatch Worked

# Send a test repository_dispatch
curl -i -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer ghp_YOUR_TOKEN" \
  https://api.github.com/repos/YOUR-ORG/central-actions/dispatches \
  -d '{"event_type":"deploy-website","client_payload":{"repo":"test","sha":"abc123"}}'

# Expected: HTTP 204 No Content (success)
# If 404: token lacks access. If 422: malformed JSON.

# Check if a workflow run was triggered
gh run list --repo YOUR-ORG/central-actions --limit 5

Interview Questions