Cross-Repository Operations

Cross-repository operations enable workflows to access code from multiple repositories and create resources (issues, PRs, comments) in external repositories. This page documents all declarative frontmatter features for cross-repository workflows.

Cross-repository features fall into three categories:

1. Code access - Check out code from multiple repositories into the workflow workspace using the checkout: frontmatter field
2. GitHub tools - Read information from other repositories using GitHub Tools with additional authentication
3. Safe outputs - Create issues, PRs, comments, and other resources in external repositories using target-repo and allowed-repos in safe outputs

All require authentication beyond the default GITHUB_TOKEN, which is scoped to the current repository only.

The checkout: frontmatter field controls how actions/checkout is invoked in the agent job. Configure custom checkout settings or check out multiple repositories.

If only a the current repository, you can use checkout: to override default checkout settings (e.g., fetch depth, sparse checkout) without needing to define a custom job:

checkout:
  fetch-depth: 0                        # Full git history
  token: ${{ secrets.MY_TOKEN }}        # Custom authentication

You can also use checkout: to check out additional repositories alongside the main repository:

checkout:
  - fetch-depth: 0
  - repository: owner/other-repo
    path: ./libs/other
    ref: main
    token: ${{ secrets.CROSS_REPO_PAT }}

Multiple checkout: configurations can target the same path and repository. This is useful for monorepos where different parts of the repository must be merged into the same workspace directory with different settings (e.g., sparse checkout for some paths, full checkout for others).

When multiple checkout: entries target the same repository and path, their configurations are merged with the following rules:

• Fetch depth: Deepest value wins (0 = full history always takes precedence)
• Sparse patterns: Merged (union of all patterns)
• LFS: OR-ed (if any config enables lfs, the merged configuration enables it)
• Submodules: First non-empty value wins for each (repository, path); once set, later values are ignored
• Ref/Token: First-seen wins

When a workflow running from a central repository targets a different repository, use current: true to tell the agent which repository to treat as its primary working target. The agent uses this as the default for all GitHub operations (creating issues, opening PRs, reading content) unless the prompt instructs otherwise. When omitted, the agent defaults to the repository where the workflow is running.

checkout:
  - repository: org/target-repo
    path: ./target
    token: ${{ secrets.CROSS_REPO_PAT }}
    current: true                                    # agent's primary target

When using GitHub Tools to read information from repositories other than the one where the workflow is running, you must configure additional authorization. The default GITHUB_TOKEN is scoped to the current repository only and cannot access other repositories.

Configure the additional authentication in your GitHub Tools configuration. For example, using a PAT:

tools:
  github:
    toolsets: [repos, issues, pull_requests]
    github-token: ${{ secrets.CROSS_REPO_PAT }}

See GitHub Tools Reference for complete details on configuring cross-repository read access for GitHub Tools.

This authentication is for reading information from GitHub. Authorization for writing to other repositories (creating issues, PRs, comments) is configured separately, see below.

Most safe output types support creating resources in external repositories using target-repo and allowed-repos parameters.

Specify a single target repository for resource creation:

safe-outputs:
  github-token: ${{ secrets.CROSS_REPO_PAT }}
  create-issue:
    target-repo: "org/tracking-repo"
    title-prefix: "[component] "

Without target-repo, safe outputs operate on the repository where the workflow is running.

Allow the agent to dynamically select from multiple repositories:

safe-outputs:
  github-token: ${{ secrets.CROSS_REPO_PAT }}
  create-issue:
    target-repo: "org/default-repo"
    allowed-repos: ["org/repo-a", "org/repo-b", "org/repo-c"]
    title-prefix: "[cross-repo] "

When allowed-repos is specified:

• Agent can include a repo field in output to select which repository
• Target repository (from target-repo or current repo) is always implicitly allowed
• Creates a union of allowed destinations

This uses multiple checkout: entries to check out different parts of the same repository with different settings:

---
on:
  pull_request:
    types: [opened, synchronize]

checkout:
  - fetch-depth: 0
  - repository: org/shared-libs
    path: ./libs/shared
    ref: main
    token: ${{ secrets.LIBS_PAT }}
  - repository: org/config-repo
    path: ./config
    sparse-checkout: |
      defaults/
      overrides/

permissions:
  contents: read
  pull-requests: read
---

# Cross-Repo PR Analysis

Analyze this PR considering shared library compatibility and configuration standards.

Check compatibility with shared libraries in `./libs/shared` and verify configuration against standards in `./config`.

This creates issues in a central tracking repository when issues are opened in component repositories:

---
on:
  issues:
    types: [opened, labeled]

permissions:
  contents: read
  issues: read

safe-outputs:
  github-token: ${{ secrets.CROSS_REPO_PAT }}
  create-issue:
    target-repo: "org/central-tracker"
    title-prefix: "[component-a] "
    labels: [tracking, multi-repo]
    max: 1
---

# Cross-Repository Issue Tracker

When issues are created in this component repository, create tracking issues in the central coordination repo.

Analyze the issue and create a tracking issue that:
- Links back to the original component issue
- Summarizes the problem and impact
- Tags relevant teams for coordination

This checks out multiple repositories and compares code patterns across them:

---
on:
  issue_comment:
    types: [created]

tools:
  github:
    toolsets: [repos, issues, pull_requests]
    github-token: ${{ secrets.CROSS_REPO_PAT }}

permissions:
  contents: read
  issues: read

safe-outputs:
  github-token: ${{ secrets.CROSS_REPO_WRITE_PAT }}
  add-comment:
    max: 1
---

# Multi-Repository Code Search

Search for similar patterns across org/repo-a, org/repo-b, and org/repo-c.

Analyze how each repository implements authentication and provide a comparison.

For direct repository access without agent involvement, use custom steps with actions/checkout:

---
engine:
  id: claude

steps:
  - name: Checkout main repo
    uses: actions/checkout@v6
    with:
      path: main-repo

  - name: Checkout secondary repo
    uses: actions/checkout@v6
    with:
      repository: org/secondary-repo
      token: ${{ secrets.CROSS_REPO_PAT }}
      path: secondary-repo

permissions:
  contents: read
---

# Compare Repositories

Compare code structure between main-repo and secondary-repo.

This approach provides full control over checkout timing and configuration.

• MultiRepoOps Pattern - Cross-repository workflow pattern
• CentralRepoOps Pattern - Central control plane pattern
• GitHub Tools Reference - Complete GitHub Tools configuration
• Safe Outputs Reference - Complete safe output configuration
• Authentication Reference - PAT and GitHub App setup
• Multi-Repository Examples - Complete working examples