Cross-Repository Operations | GitHub Agentic Workflows
Skip to main content 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: Cross-Repository Checkout - Check out code from other repositories Cross-Repository Reading - Read issues, pull requests and other information from other repositories Cross-Repository Safe Outputs - Create issues, PRs, comments, and other resources in external repositories using target-repo and allowed-repos in safe outputs All require additional authentication.
Cross-Repository Checkout ( checkout: ) Section titled “Cross-Repository Checkout (checkout:)” The checkout: frontmatter field controls how actions/checkout is invoked in the agent job. Use it to check out one or more repositories, override fetch depth or sparse-checkout settings, fetch additional refs (e.g., all open PR branches), or disable checkout entirely with checkout: false . For multi-repository workflows, list multiple entries to clone several repos into the workspace.
Mark the agent’s primary target with current: true when working from a central repository that targets a different repo. For sidecar workflows that only need to check out a target repository and not their own, set permissions.contents: none to skip the automatic workflow-repository checkout while keeping other configured checkout: entries intact — see Target-Only Checkout . When current: true points to a checkout in a subdirectory, pull-request patch generation for create-pull-request and push-to-pull-request-branch runs from that checkout path (when targeting that repository).
This ensures PR patches include the real file changes instead of workspace-root gitlinks/subproject entries. checkout : - fetch-depth : 0 # checkout this repository with full history fetch : [ " refs/pulls/open/* " ] # fetch all open PR branches after checkout - repository : owner/other-repo # another repository to check out path : ./libs/other # path within workspace to check out to github-token : ${{ secrets.CROSS_REPO_PAT }} # additional auth for cross-repo access See GitHub Repository Checkout for the full configuration reference, including fetch options, sparse checkout, merging rules, and examples.
Cross-Repository Reading Section titled “Cross-Repository Reading” The GitHub Tools are used to read information such as issues and pull requests from repositories. By default, these tools can access the current repository and all public repositories (if permitted by the network firewall). Authorizing Additional Cross-Repository Reading Section titled “Authorizing Additional Cross-Repository Reading” To read from other private repositories, you must configure additional authorization.
Configure a PAT or GitHub App in your GitHub Tools configuration: tools : github : toolsets : [ repos , issues , pull_requests ] github-token : ${{ secrets.CROSS_REPO_PAT }} This enables operations like: Reading files and searching code in external repositories dynamically, even if the repository is not checked out Querying issues and pull requests from other repos Accessing commits, releases, and workflow runs across repositories Reading organization-level information See Additional Authentication for GitHub Tools for full details on creating a PAT, using a GitHub App, or using the magic secret GH_AW_GITHUB_MCP_SERVER_TOKEN .
Restricting Cross-Repository Reading ( tools.github.allowed-repos ) Section titled “Restricting Cross-Repository Reading (tools.github.allowed-repos)” You can also configure the GitHub Tools to be restricted in which repositories can be accessed via the GitHub tools during AI engine execution by using the tools.github.allowed-repos setting. This is a guardrail to prevent unintended access to repositories. The setting tools.github.allowed-repos specifies which repositories the agent can access through GitHub tools: "all" — All repositories accessible by the configured token "public" — Public repositories only "current" — The repository where the workflow is running (normalized to ${{ github.repository }} in the emitted guard policy) "${{ github.repository }}" — Equivalent to "current" , kept for backward compatibility Array of patterns — Specific repositories and wildcards: "owner/repo" — Exact repository match "owner/*" — All repositories under an owner "owner/prefix*" — Repositories with a name prefix under an owner This defaults to "all" when omitted.
Patterns must be lowercase. Wildcards are only permitted at the end of the repository name component. Use current in reusable or generated workflows that need to express “this repository only” without hard-coding owner/repo : tools : github : toolsets : [ issues , pull_requests ] allowed-repos : current min-integrity : approved For example: tools : github : mode : remote toolsets : [ default ] allowed-repos : - " myorg/* " - " partner/shared-repo " - " myorg/api-* " min-integrity : approved Cross-Repository Safe Outputs Section titled “Cross-Repository Safe Outputs” Most safe output types support creating resources in external repositories using target-repo and allowed-repos parameters.
Target Repository ( safe-outputs.*.target-repo ) Section titled “Target Repository (safe-outputs.*.target-repo)” 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. Wildcard Target Repository ( target-repo: "*" ) Section titled “Wildcard Target Repository (target-repo: "*")” Set target-repo: "*" to allow the agent to dynamically target any repository at runtime.
When configured, the agent receives a repo parameter in its tool call where it supplies the target repository in owner/repo format: safe-outputs : github-token : ${{ secrets.CROSS_REPO_PAT }} create-issue : target-repo : " * " title-prefix : " [component] " Use this when the target repository is not known at workflow authoring time — for example, when building a workflow that routes issues to different repositories based on labels or content.
Allowed Repositories ( safe-outputs.*.allowed-repos ) Section titled “Allowed Repositories (safe-outputs.*.allowed-repos)” Allow your agentic workflow 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: The agentic step can include a repo field to select which repository Target repository (from target-repo or current repo) is always implicitly allowed Creates a union of allowed destinations Checkout Requirement for Pull Request Outputs Section titled “Checkout Requirement for Pull Request Outputs” Unlike other safe output types, create-pull-request and push-to-pull-request-branch with a cross-repository target require the target repository to be checked out into the workflow workspace .
This also applies when the target is resolved from GH_AW_TARGET_REPO_SLUG . You can use either a checkout: frontmatter entry with a path: specified or a custom steps: entry that clones the repository under $GITHUB_WORKSPACE . Without a target checkout, these handlers return an error instead of generating a patch from the workflow repository. Safe outputs first consult the checkout manifest produced by checkout: entries, then fall back to scanning $GITHUB_WORKSPACE for git repositories and matching them by remote.origin.url .
Commit changes in the target checkout against the intended target base branch. Reading a target file through GitHub tools and copyi
The rest of this page is on the live site.