From 6a36fae8861d82d1c63f0cb9c967a4d7f3cba439 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 7 Sep 2026 19:12:07 +0000 Subject: [PATCH] Add side quest: orchestrate across multiple repositories Adds a new enterprise-focused side quest branching from Step 28 (Orchestrate Multiple Agentic Workflows) covering target-repo, allowed-repos, and cross-repository checkout for hub-and-spoke orchestration across a multi-repository estate. Links added from 28-orchestrate-workflows.md and workshop/README.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- workshop/28-orchestrate-workflows.md | 3 + workshop/README.md | 1 + ...de-quest-28-01-cross-repo-orchestration.md | 101 ++++++++++++++++++ 3 files changed, 105 insertions(+) create mode 100644 workshop/side-quest-28-01-cross-repo-orchestration.md diff --git a/workshop/28-orchestrate-workflows.md b/workshop/28-orchestrate-workflows.md index c25eebb8..efe0a873 100644 --- a/workshop/28-orchestrate-workflows.md +++ b/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 diff --git a/workshop/README.md b/workshop/README.md index 83fe2472..9e1365c7 100644 --- a/workshop/README.md +++ b/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 diff --git a/workshop/side-quest-28-01-cross-repo-orchestration.md b/workshop/side-quest-28-01-cross-repo-orchestration.md new file mode 100644 index 00000000..66a559cb --- /dev/null +++ b/workshop/side-quest-28-01-cross-repo-orchestration.md @@ -0,0 +1,101 @@ + + + + +# 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 + + +Return to [Orchestrate Multiple Agentic Workflows](28-orchestrate-workflows.md). +