Add formal checkout behavior specification for agent and safe_outputs jobs by Copilot · Pull Request #44225 · github/gh-aw

Copilot · 2026-07-08T06:27:23Z

Checkout behavior is currently distributed across compiler/runtime paths, which makes auth precedence and mode-specific semantics hard to reason about quickly. This PR introduces a single formal specification for checkout behavior across activation, agent, and safe_outputs jobs, including trial mode and side-repo cases.

Specification baseline (W3C/RFC2119)
- Added docs/src/content/docs/specs/checkout-behavior-specification.md.
- Defines normative checkout behavior and conformance classes for compiler/runtime paths.
Authentication and credential lifecycle
- Specifies precedence for github-token and github-app at checkout entry level, activation token resolution, and safe_outputs PR checkout token resolution.
- Codifies the credential boundary: agent job defaults to credential stripping; safe_outputs PR path retains/configures credentials for fetch/push handlers.
Checkout mechanics and safety constraints
- Documents checkout: merge behavior for repeated (repository, path, wiki) targets.
- Specifies fetch-depth, fetch, sparse checkout partial-clone repair, and submodule credential-cleanup behavior.
- Specifies checkout-manifest path safety and manifest-first lookup semantics for multi-repo handler resolution.
- Captures activation sparse-checkout symlink target handling and root-escape rejection requirements.
Trial mode and side-repo targeting
- Specifies trial-mode repository/token override behavior for checkout and safe-output targeting.
- Specifies side-repo target derivation from current: true checkouts and side-repo auth precedence.
Reference docs linkage
- Linked the new spec from docs/src/content/docs/reference/checkout.md.

checkout:
  - repository: org/target-repo
    path: target
    github-app:
      client-id: ${{ vars.APP_ID }}
      private-key: ${{ secrets.APP_PRIVATE_KEY }}
    fetch-depth: 0
    fetch: ["main", "refs/pulls/open/*"]
    sparse-checkout: |
      .github
      pkg/workflow
    submodules: recursive
    force-clean-git-credentials: true

Generated by 👨‍🍳 PR Sous Chef · 9.91 AIC · ⌖ 10.6 AIC · ⊞ 7.1K · ◷
_{Comment /souschef to run again}

Generated by 👨‍🍳 PR Sous Chef · 6.93 AIC · ⌖ 5.06 AIC · ⊞ 7.1K · ◷
_{Comment /souschef to run again}

Generated by 👨‍🍳 PR Sous Chef · 6.55 AIC · ⌖ 5.29 AIC · ⊞ 7.1K · ◷
_{Comment /souschef to run again}

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

pelikhan · 2026-07-08T06:40:37Z

@copilot merge main and recompile

…out-behavior Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-07-08T07:03:20Z

@copilot merge main and recompile

Done in 1a913a0: merged main and recompiled workflow lock files.

github-actions · 2026-07-08T07:17:33Z

🤖 PR Triage

Field	Value
Category	`docs`
Risk	🟢 Low
Score	22/100 (impact:10 urgency:7 quality:5)
Action	`defer`

Rationale: Draft PR adding a checkout behavior specification doc. Pure documentation, no code logic changes. Hold until ready for review (undraft).

Run §28924016278

Generated by 🔧 PR Triage Agent · 101 AIC · ⌖ 9.82 AIC · ⊞ 5.4K · ◷

pelikhan · 2026-07-08T07:19:41Z

@copilot revert lock.yml files

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-07-08T07:36:39Z

@copilot revert lock.yml files

Done in a90e088: reverted the .lock.yml file changes.

pelikhan

@copilot checkout item must support a field to specify credentials to be used in safe-outputs

checkout:
...
safe-output-github-token: ...
safe-output-github-app: ...

pelikhan · 2026-07-08T12:00:08Z

+- Symlink handling for activation sparse checkout
+- Submodule credential cleanup behavior
+- Trial mode and side-repo derivation behavior
+


@copilot also handle checkout manifest generation

Done in f4562a1: added normative checkout-manifest generation requirements, including safe-outputs auth metadata handling and no persisted resolved tokens.

Section 3.4 (Checkout Manifest) was added in f4562a1 and is in the current spec — see lines 111–118 of checkout-behavior-specification.md. It covers the compiler requirement to emit a manifest step, manifest-path safety (absolute/out-of-workspace rejection), and the requirement to include safe_outputs auth metadata without persisting resolved token values.

gh-aw-bot · 2026-07-08T16:03:00Z

@copilot please run the pr-finisher skill, ensure the branch is up to date, and rerun checks.

Generated by 👨‍🍳 PR Sous Chef · 6.93 AIC · ⌖ 5.06 AIC · ⊞ 7.1K · ◷
_{Comment /souschef to run again}

…out-behavior Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

Copilot · 2026-07-08T16:28:07Z

@copilot please run the pr-finisher skill, ensure the branch is up to date, and rerun checks.

...

Branch updated: merged main (d4fdc968b5 — docs-only, no tooling drift). Local validation passes (make fmt, make lint, make test-unit all green). All open review threads have been addressed and replied to. CI needs a human re-trigger (close/reopen or workflow_dispatch) to run on the current HEAD.

gh-aw-bot · 2026-07-08T16:49:24Z

@copilot please run the pr-finisher skill, make any remaining updates needed to get this PR ready, and rerun checks once the branch is up to date.

Generated by 👨‍🍳 PR Sous Chef · 6.55 AIC · ⌖ 5.29 AIC · ⊞ 7.1K · ◷
_{Comment /souschef to run again}

#42926) Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

Copilot · 2026-07-08T17:07:22Z

@copilot please run the pr-finisher skill, make any remaining updates needed to get this PR ready, and rerun checks once the branch is up to date.

...

Done. Here's what was addressed in this pass:

Issue safe_outputs default checkout of workflow repo uses safe-outputs.github-app token, breaking cross-org workflows #42926 fix in spec §4.3: safe-outputs.github-app and safe-outputs.github-token are now explicitly excluded from resolvePRCheckoutToken — they govern PR/push operations only, not checkout. The safe_outputs job uses only per-checkout safe-output-github-app (if set) or GITHUB_TOKEN fallback for checkout tokens. This is the normative fix for the cross-org auth failure.
Reference docs: added a "Cross-Organization safe_outputs Authentication" section with a worked example showing how safe-output-github-app solves the issue safe_outputs default checkout of workflow repo uses safe-outputs.github-app token, breaking cross-org workflows #42926 scenario. Shortened the table cell description to link to the new section.
T-CHK-012 updated to reflect the new exclusion requirement.
Branch is current with main (merged in commit 11bd0ed); local validation (make fmt, make lint, make test-unit, make agent-report-progress) all pass.

CI needs a human re-trigger (close/reopen or push) after this push to verify on the current HEAD.

gh-aw-bot · 2026-07-08T17:30:00Z

pr-sous-chef
@copilot please run the pr-finisher skill, address any unresolved review feedback, and rerun checks once the branch is up to date.

Generated by 👨‍🍳 PR Sous Chef · 6.43 AIC · ⌖ 4.84 AIC · ⊞ 7.1K · ◷
_{Comment /souschef to run again}

…out-behavior Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

Copilot · 2026-07-08T17:39:59Z

pr-sous-chef
@copilot please run the pr-finisher skill, address any unresolved review feedback, and rerun checks once the branch is up to date.
...

Done in 795ae59: merged latest main (docs-only commit 2877be8). Local validation passes (make agent-report-progress green, no tooling drift). All review feedback was addressed in prior commits. CI needs a human re-trigger to run on the current HEAD.

github-actions · 2026-07-08T18:57:00Z

🤖 PR Triage

Field	Value
Category	docs
Risk	🟢 low
Score	21/100 (impact:10 urgency:5 quality:6)
Action	⏸ defer

Status: Carry-over (run 4) · CI unstable.

Pure docs spec: formal checkout behavior specification for agent and safe_outputs jobs. Persists across 4 runs with CI unstable. ⚠️ Consider closing if CI issue is not resolved — spec value is low relative to carry-over cost.

Run §28966928999

Generated by 🔧 PR Triage Agent · 106.9 AIC · ⌖ 10.9 AIC · ⊞ 5.4K · ◷

gh-aw-bot · 2026-07-08T19:29:32Z

pr-sous-chef
@copilot please run the pr-finisher skill, address any unresolved review feedback (including the safe-outputs checkout credential field request), and rerun checks once the branch is up to date.

Run: https://github.com/github/gh-aw/actions/runs/28969326363

Generated by 👨‍🍳 PR Sous Chef · 10.3 AIC · ⌖ 7.04 AIC · ⊞ 7.1K · ◷
_{Comment /souschef to run again}

…out-behavior Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

Copilot · 2026-07-08T19:45:45Z

pr-sous-chef
@copilot please run the pr-finisher skill, address any unresolved review feedback (including the safe-outputs checkout credential field request), and rerun checks once the branch is u...

Done in ac24527: merged latest main (docs-only commit c342483). Local validation passes (make agent-report-progress green, no tooling drift).

Summary of where things stand:

✅ Reviews — All in-scope review feedback was addressed in prior commits. Three threads have replies but the GraphQL API is not accessible in this environment to mark them resolved — they will need a human to resolve:
- §3.4 checkout manifest thread: addressed in f4562a1, replied twice confirming it is done.
- app alias thread: addressed in c0968e3, replied confirming the fix.
- safe-output-github-token ordering thread: moot since 045bf15 removed the token field; replied confirming it is now moot.
✅ Checks (local) — make agent-report-progress green: 0 lint errors, all 259 workflow lock files in sync.
❓ Checks (CI) — Stale after agent push; needs human re-trigger. Prior CI run (28969931366) was in progress at triage; no prior failures to address.
✅ Mergeable — Branch is OPEN, not draft, up to date with main.

Hand-off: CI must be re-triggered by a maintainer (close/reopen PR, workflow_dispatch, or push) before merge. Three unresolved review threads need manual resolution since the GraphQL mutation endpoint is blocked in this environment.

github-actions · 2026-07-09T04:05:25Z

🎉 This pull request is included in a new release.

Release: v0.82.7

Copilot AI and others added 3 commits July 8, 2026 06:16

Plan checkout behavior specification

4c3a990

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Add checkout behavior specification

8e60d71

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Refine checkout spec validation language

63ab086

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI assigned Copilot and pelikhan Jul 8, 2026

Copilot AI changed the title ~~Add formal checkout behavior specification for agent and safe outputs jobs~~ Add formal checkout behavior specification for agent and safe_outputs jobs Jul 8, 2026

Copilot created this pull request from a session on behalf of pelikhan July 8, 2026 06:28 View session

Copilot finished work on behalf of pelikhan July 8, 2026 06:28

Copilot AI requested a review from pelikhan July 8, 2026 06:28

Copilot started work on behalf of pelikhan July 8, 2026 06:41 View session

Copilot AI and others added 2 commits July 8, 2026 06:53

Merge remote-tracking branch 'origin/main' into copilot/specify-check…

fee4a9f

…out-behavior Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Merge main and recompile workflow lock files

1a913a0

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot finished work on behalf of pelikhan July 8, 2026 07:04

github-actions Bot added pr-action:defer pr-agent:copilot pr-priority:low pr-risk:low pr-type:docs labels Jul 8, 2026

github-actions Bot mentioned this pull request Jul 8, 2026

[PR Triage Report] [PR Triage] 2026-07-08 — 11 open Copilot PRs — Run §28924016278 #44236

Closed

Copilot started work on behalf of pelikhan July 8, 2026 07:20 View session

Plan: revert lock.yml changes

a90e088

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot finished work on behalf of pelikhan July 8, 2026 07:37

github-actions Bot mentioned this pull request Jul 8, 2026

[aw] No-Op Runs #43499

Open

pelikhan reviewed Jul 8, 2026

View reviewed changes

Copilot started work on behalf of pelikhan July 8, 2026 12:05 View session

github-actions Bot mentioned this pull request Jul 8, 2026

[pr-sous-chef] Run report — 6 nudged, 0 skipped #44348

Closed

Copilot started work on behalf of gh-aw-bot July 8, 2026 16:15 View session

Merge remote-tracking branch 'origin/main' into copilot/specify-check…

11bd0ed

…out-behavior Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

Copilot finished work on behalf of gh-aw-bot July 8, 2026 16:28

Copilot started work on behalf of gh-aw-bot July 8, 2026 16:50 View session

Copilot AI and others added 2 commits July 8, 2026 17:04

docs: fix §4.3 - safe-outputs auth must not be used for checkout (issue

f909134

#42926) Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

docs: shorten safe-output-github-app table description, link to section

2155164

Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

Copilot finished work on behalf of gh-aw-bot July 8, 2026 17:08

github-actions Bot mentioned this pull request Jul 8, 2026

[pr-sous-chef] Run report — 5 nudged, 0 skipped #44369

Closed

Copilot started work on behalf of gh-aw-bot July 8, 2026 17:30 View session

Merge remote-tracking branch 'origin/main' into copilot/specify-check…

795ae59

…out-behavior Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

Copilot finished work on behalf of gh-aw-bot July 8, 2026 17:40

github-actions Bot mentioned this pull request Jul 8, 2026

[pr-sous-chef] Run report — 0 nudged, 4 skipped #44393

Closed

github-actions Bot mentioned this pull request Jul 8, 2026

[PR Triage Report] PR Triage Report — 2026-07-08 [§28966928999] #44396

Closed

github-actions Bot mentioned this pull request Jul 8, 2026

[pr-sous-chef] Run report — 5 nudged, 2 skipped #44408

Closed

Copilot started work on behalf of gh-aw-bot July 8, 2026 19:30 View session

Merge remote-tracking branch 'origin/main' into copilot/specify-check…

ac24527

…out-behavior Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

Copilot finished work on behalf of gh-aw-bot July 8, 2026 19:46

pelikhan merged commit a7fb8aa into main Jul 8, 2026

pelikhan deleted the copilot/specify-checkout-behavior branch July 8, 2026 20:21

Uh oh!

Conversation

Copilot AI commented Jul 8, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pelikhan commented Jul 8, 2026

Uh oh!

Copilot AI commented Jul 8, 2026

Uh oh!

github-actions Bot commented Jul 8, 2026

🤖 PR Triage

Uh oh!

pelikhan commented Jul 8, 2026

Uh oh!

Copilot AI commented Jul 8, 2026

Uh oh!

pelikhan left a comment

Choose a reason for hiding this comment

Uh oh!

pelikhan Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

gh-aw-bot commented Jul 8, 2026

Uh oh!

Copilot AI commented Jul 8, 2026

Uh oh!

gh-aw-bot commented Jul 8, 2026

Uh oh!

Copilot AI commented Jul 8, 2026

Uh oh!

gh-aw-bot commented Jul 8, 2026

Uh oh!

Copilot AI commented Jul 8, 2026

Uh oh!

github-actions Bot commented Jul 8, 2026

🤖 PR Triage

Uh oh!

gh-aw-bot commented Jul 8, 2026

Uh oh!

Copilot AI commented Jul 8, 2026

Uh oh!

github-actions Bot commented Jul 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Jul 8, 2026 •

edited by github-actions Bot

Loading