Skip to content

docs: add working-directory navigation example to side-repo-ops pattern #26123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Apr 14, 2026
Merged

docs: add working-directory navigation example to side-repo-ops pattern #26123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4581705
Initial plan
Copilot Apr 14, 2026
c670306
docs: add working-directory navigation example to side-repo-ops pattern
Copilot Apr 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions docs/src/content/docs/patterns/side-repo-ops.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Copilot AI Apr 14, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sentence "has been checked out into" reads awkwardly (double “into”). Rephrase the instruction to something like "Navigate to the checked-out repository: cd …" or "Navigate into the checked-out repository directory: cd …".

Suggested change
Navigate into the folder where the target repository has been checked out into: cd ${{ github.workspace }}/repo
Navigate to the checked-out repository: cd ${{ github.workspace }}/repo

Copilot uses AI. Check for mistakes.

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.
Expand Down
9 changes: 9 additions & 0 deletions docs/src/content/docs/reference/checkout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Copilot AI Apr 14, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The phrase "has been checked out into" is ungrammatical (double “into”) and may read awkwardly in the example prompt. Consider rephrasing to something like "checked out to" / "checked out at" / "checked out in" (e.g., "Navigate to the checked-out repository: cd …").

Suggested change
> Navigate into the folder where the target repository has been checked out into: cd ${{ github.workspace }}/target
> Navigate to the checked-out target repository: cd ${{ github.workspace }}/target

Copilot uses AI. Check for mistakes.
> ```
>
> 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).
Expand Down
Loading