From 4581705c4be63bbf8c4ba9067849aa60e94c464f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 14 Apr 2026 00:47:42 +0000
Subject: [PATCH 1/2] Initial plan


From c67030646614b953b112aa142c1f929818bd08a1 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 14 Apr 2026 00:57:32 +0000
Subject: [PATCH 2/2] docs: add working-directory navigation example to
 side-repo-ops pattern

Adds a 'Checking Out the Target Repository' subsection under Advanced
Topics in side-repo-ops.mdx, demonstrating how to combine checkout with
current: true and an explicit path:, plus an explicit cd instruction in
the prompt.

Also adds an IMPORTANT callout to checkout.md clarifying that current:
true annotates the agent prompt only and does not set the working
directory automatically.

Closes #<issue-number>"

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/98aa008e-1840-46fa-b806-234f5eca6882

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .../content/docs/patterns/side-repo-ops.mdx   | 41 +++++++++++++++++++
 docs/src/content/docs/reference/checkout.md   |  9 ++++
 2 files changed, 50 insertions(+)

diff --git a/docs/src/content/docs/patterns/side-repo-ops.mdx b/docs/src/content/docs/patterns/side-repo-ops.mdx
index 20393c9d93a..2ecd092f753 100644
--- a/docs/src/content/docs/patterns/side-repo-ops.mdx
+++ b/docs/src/content/docs/patterns/side-repo-ops.mdx
@@ -440,6 +440,47 @@ safe-outputs:
 Work on user-specified repository: {{inputs.target_repo}}
 ```
 
+### Checking Out the Target Repository
+
+When your workflow needs to run local tools against the target repository (for example, running tests, linters, or build scripts), check it out to a named path and explicitly navigate the agent into that directory:
+
+```aw wrap
+---
+on:
+  workflow_dispatch:
+    inputs:
+      target_repo:
+        description: "Target repository (owner/repo)"
+        required: true
+
+checkout:
+  - repository: ${{ github.event.inputs.target_repo }}
+    path: repo
+    github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }}
+    current: true
+
+engine: copilot
+
+permissions:
+  contents: read
+
+safe-outputs:
+  github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }}
+  create-pull-request:
+    target-repo: ${{ inputs.target_repo }}
+    base-branch: main
+---
+
+# Run Tests in Target Repository
+
+Navigate into the folder where the target repository has been checked out into: cd ${{ github.workspace }}/repo
+
+Run the test suite and report any failures.
+```
+
+> [!IMPORTANT]
+> `current: true` tells the agent which repository to treat as its primary target for GitHub operations — it does **not** automatically set the working directory. Without the explicit `cd` instruction in the prompt, the agent starts in `$GITHUB_WORKSPACE` (the side repository checkout) and must infer the correct directory on its own, which can lead to mistakes.
+
 ### Using GitHub Apps
 
 For enhanced security, use GitHub Apps instead of PATs.
diff --git a/docs/src/content/docs/reference/checkout.md b/docs/src/content/docs/reference/checkout.md
index 287dda18f72..cea3db64407 100644
--- a/docs/src/content/docs/reference/checkout.md
+++ b/docs/src/content/docs/reference/checkout.md
@@ -119,6 +119,15 @@ checkout:
     current: true                                    # agent's primary target
 ```
 
+> [!IMPORTANT]
+> `current: true` only annotates the agent's system prompt to identify the target repository — it does **not** automatically change the working directory. If the agent needs to run local tools (tests, linters, build scripts) against the checked-out repository, add an explicit `cd` instruction to the prompt:
+>
+> ```
+> Navigate into the folder where the target repository has been checked out into: cd ${{ github.workspace }}/target
+> ```
+>
+> Without this instruction, the agent starts in `$GITHUB_WORKSPACE` (the side repository checkout) and must infer the correct directory on its own.
+
 ## Checkout Merging
 
 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).