[workshop] Add node: Orchestrate Across Multiple Repositories

workshop/28-orchestrate-workflows.md

@@ -156,6 +156,9 @@ the latest commit is more than 48 hours old and no status issue was created toda
 
 Each iteration follows the same loop: edit the brief, compile, push, run, inspect the dispatch log.
 
+> [!NOTE]
+> Working across multiple repositories (a hub-and-spoke tracking repo, shared libraries) instead of one? See [Side Quest: Orchestrate Across Multiple Repositories](side-quest-28-01-cross-repo-orchestration.md) for `target-repo` and cross-repository checkout.
+
 ## :white_check_mark: Checkpoint
 
 - [ ] You identified at least two specialist workflows and one orchestration condition for each

workshop/README.md

@@ -106,6 +106,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo
 - [Self-Hosted Runner Infrastructure Deep Dive](side-quest-24-01-runner-infrastructure.md) — enterprise infrastructure primer covering ephemeral and JIT runners, proxy configuration, and network isolation for air-gapped environments; branches from [Step 24](24-self-hosted-runners.md).
 - [Project Future AI Credit Costs with `gh aw forecast`](side-quest-26-01-forecast-costs.md) — full walkthrough of `gh aw forecast`: reading P10/P50/P90 output, using `--period week` and `--days 7`, forecasting all workflows, and deriving a `max-daily-ai-credits` value from the P90 figure; branches from [Step 26](26-manage-costs-and-budgets.md).
 - [Skill Injection Strategies — Hint, Fusion, and Inline](side-quest-29-01-skill-injection-strategies.md) — decision table, code examples, and a practice exercise for the hint, fusion, and inline strategies for wiring a `SKILL.md` into a workflow prompt; branches from [Step 29](29-skills-and-domain-knowledge.md).
+- [Orchestrate Across Multiple Repositories](side-quest-28-01-cross-repo-orchestration.md) — enterprise-focused guide to `target-repo`, `allowed-repos`, and cross-repository `checkout:` for hub-and-spoke orchestration across a multi-repository estate; branches from [Step 28](28-orchestrate-workflows.md).
 - [Recognizing Common Agentic Workflow Failure Modes](side-quest-22-01-failure-modes.md) — worked examples of empty data, tool error, timeout, and prompt drift failures with a match-the-fix practice exercise; branches from [Step 22](22-error-handling-and-resilience.md).
 
 ## Getting Started

workshop/side-quest-28-01-cross-repo-orchestration.md

@@ -0,0 +1,101 @@
+<!-- page-journey: all -->
+<!-- page-adventure: side-quest -->
+<!--
+<research-metadata>
+  <focus>Cross-repository safe outputs (target-repo, allowed-repos) and cross-repository checkout for orchestrating agentic workflows across a multi-repository or enterprise estate</focus>
+  <sources>
+    <source>https://github.github.com/gh-aw/reference/cross-repository/</source>
+    <source>https://github.github.com/gh-aw/reference/checkout/</source>
+    <source>https://github.github.com/gh-aw/reference/github-tools/</source>
+  </sources>
+  <rationale>Step 28 teaches single-repository orchestration with dispatch-workflow, but many enterprise estates split work across multiple repositories (a hub-and-spoke tracking repo, shared libraries, per-team component repos). No existing node covers target-repo, allowed-repos, or the extra github-token needed for cross-repo authentication. This side quest closes that gap for enterprise learners managing multi-repo orchestration.</rationale>
+</research-metadata>
+-->
+
+# Side Quest: Orchestrate Across Multiple Repositories
+
+> _Enterprise estates rarely fit in one repository — extend your orchestrator to read and write across repos safely._
+
+## :dart: What You'll Do
+
+You'll learn how `target-repo`, `allowed-repos`, and cross-repository `checkout:` let a single orchestrator workflow read from and create resources in repositories other than the one it runs in — the pattern enterprise teams use for hub-and-spoke tracking across many component repos.
+
+## :clipboard: Before You Start
+
+- You completed [Orchestrate Multiple Agentic Workflows](28-orchestrate-workflows.md).
+- You have (or can request) admin access to create a fine-grained PAT or GitHub App credential for a second repository.
+- Your enterprise admin can confirm whether cross-repository PATs are permitted by org policy.
+
+## Understand cross-repository authentication
+
+`GITHUB_TOKEN` only grants access to the repository where a workflow runs. To read or write another repository, your workflow needs additional authentication — a PAT or GitHub App token stored as a secret.
+
+> [!NOTE]
+> On GHES or GHEC with restricted PAT policies, ask your admin whether a GitHub App is required instead of a personal PAT for cross-repo automation.
+
+## Steps
+
+### Add a target repository to a safe output
+
+Most [safe-outputs](https://github.github.com/gh-aw/reference/safe-outputs/) support `target-repo` to create resources in a different repository than the one running the workflow:
+
+```yaml
+safe-outputs:
+  github-token: ${{ secrets.CROSS_REPO_PAT }}
+  create-issue:
+    target-repo: "org/tracking-repo"
+    title-prefix: "[component] "
+```
+
+This is the **hub-and-spoke** pattern: several component-repo orchestrators file issues into one central tracking repository your enterprise team monitors.
+
+### Allow the agent to pick from several repositories
+
+If the target isn't known until runtime, use `allowed-repos` so the agent can choose:
+
+```yaml
+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"]
+```
+
+The agent's tool call can then include a `repo` field, and gh-aw enforces that it only matches an allowed entry.
+
+### Check out a second repository for context
+
+To let the agent read files from another repository (not just create issues in it), add a `checkout:` entry with a `path:`:
+
+```yaml
+checkout:
+  - fetch-depth: 0
+  - repository: org/shared-libs
+    path: ./libs/shared
+    github-token: ${{ secrets.CROSS_REPO_PAT }}
+```
+
+> :thinking: **Predict:** If you omit `github-token:` on the second checkout entry and `org/shared-libs` is private, what happens? Check your answer by reading the [Cross-Repository Checkout](https://github.github.com/gh-aw/reference/cross-repository/#cross-repository-checkout-checkout) reference — the checkout fails silently or errors with a permission message, depending on visibility.
+
+### Extend your orchestrator
+
+Update `repo-orchestrator.md` to route findings into a central tracking repo, then compile:
+
+```bash
+gh aw compile repo-orchestrator
+```
+
+Confirm the compiled `.lock.yml` includes the `CROSS_REPO_PAT` secret reference and the `target-repo` value you configured.
+
+## :white_check_mark: Checkpoint
+
+- [ ] You can explain why `GITHUB_TOKEN` alone cannot reach other repositories
+- [ ] You added `target-repo` to a safe output and understand the hub-and-spoke pattern
+- [ ] You can explain the difference between `target-repo` and `allowed-repos`
+- [ ] You added a `checkout:` entry with `path:` and `github-token:` for a second repository
+- [ ] `gh aw compile repo-orchestrator` succeeded after your cross-repo changes
+- [ ] You know whether your enterprise's PAT policy requires a GitHub App instead
+
+<!-- journey: all -->
+Return to [Orchestrate Multiple Agentic Workflows](28-orchestrate-workflows.md).
+<!-- /journey -->