Clarify checkout, safe-outputs, and cross-repo credential precedence

[Copilot]

The checkout specification did not clearly define how implicit safe-outputs checkouts relate to the agent checkout, the shared checkout manager, and cross-repository write flows. It also left ambiguity around whether safe-outputs could override checkout-scoped github-token / github-app credentials, especially in side-repo and trial-target scenarios.

• Checkout model

  • Document that checkout: is compiled once through the checkout manager and reused by both the agent job and the trusted safe_outputs job.
  • Clarify that the implicit safe-outputs checkout only exists for content-writing git operations such as create-pull-request and push-to-pull-request-branch.

• Credential boundaries

  • Make the agent vs safe-outputs split explicit:
    • agent job checkouts remove credentials after checkout
    • safe-outputs checkouts retain credentials only in the trusted write path
  • State unambiguously that checkout-level github-token / github-app settings are never overwritten by safe-outputs, and there is no separate syntax to override them indirectly.

• Fallback token precedence

  • Refine the PR/push documentation to distinguish:
    • checkout-specific credentials that stay authoritative for that checkout
    • the single fallback safe-outputs token used only when a checkout entry has no credentials of its own
  • Clarify the precedence between per-output tokens, safe-outputs.github-app, safe-outputs.github-token, and the default GitHub token.

• Cross-repo targeting

  • Clarify that current: true helps select patch workspace for PR-writing handlers, but does not retarget writes by itself.
  • Document that side-repo workflows still need explicit safe-outputs.*.target-repo to write back to the main repository.
  • Clarify that trial target repo defaults apply only when target-repo is omitted, and explicit target-repo wins.

checkout:
- repository: org/target-repopath: ./targetgithub-token: ${{ secrets.CROSS_REPO_PAT }}current: truesafe-outputs:
github-token: ${{ secrets.SAFE_OUTPUTS_PAT }}push-to-pull-request-branch:
target-repo: "org/target-repo"

In this shape, the checkout keeps using checkout.github-token; safe-outputs.github-token is only fallback for checkouts that did not declare their own credentials.

[github-actions]

Hey @Copilot 👋 — great work on this documentation clarification! The changes to checkout.md, cross-repository.md, and safe-outputs-pull-requests.md collectively resolve real ambiguities around credential precedence and the agent vs. safe-outputs split — exactly the kind of documentation gap that causes confusion in practice.

The PR body is thorough and well-structured, the diff is tightly scoped to a single concern, and the SKILL.md cleanup is a nice bonus. This looks ready for review.

Generated by ✅ Contribution Check · 356.5 AIC · ⌖ 15.2 AIC · ⊞ 6.3K · ◷

[github-actions]

🤖 PR Triage

Field	Value
Category	docs
Risk	🟢 Low
Score	28/100 (Impact 10 + Urgency 8 + Quality 10)
Action	⏸️ defer

Score Breakdown

• Impact (10/50): Documentation clarification for checkout/safe-outputs credential precedence — useful but not blocking
• Urgency (8/30): Draft PR; no CI; bot comments indicate "nice work" but content still in flux; 4 files, 27 adds, 16 deletes
• Quality (10/20): Doc-only change; draft status; multiple bot comments suggesting it needs refinement

Defer until author marks ready for review.

Generated by 🔧 PR Triage Agent · 92.3 AIC · ⌖ 6.73 AIC · ⊞ 5.5K · ◷

[github-actions]

🤖 PR Triage (updated)

Field	Value
Category	docs
Risk	🟢 Low
Score	28 / 100
Action	⏸ defer

Score breakdown: Impact 12 (clarifies credential precedence docs) + Urgency 8 + Quality 8

DRAFT — low-priority documentation clarification. Defer until active checkout/credential work surfaces.

Generated by 🔧 PR Triage Agent · 82.8 AIC · ⌖ 8.09 AIC · ⊞ 5.5K · ◷

[github-actions]

🤖 PR Triage — Run §28706384347

Field	Value
Category	docs
Risk	🟢 Low
Score	28 / 100
Action	💤 defer

Score breakdown: impact 12 + urgency 8 + quality 8

Clarifies checkout/safe-outputs/cross-repo credential precedence in docs (+27/-16, 4 files). Low urgency, draft, no CI. Carried over from prior run — continue to defer until a docs batch forms.

Generated by 🔧 PR Triage Agent · 56.5 AIC · ⌖ 8.62 AIC · ⊞ 5.5K · ◷

[github-actions]

🤖 PR Triage — Run §28715668077

Field	Value
Category	docs
Risk	🟢 Low
Score	28/100
Action	⏸️ defer

Carry-over — still draft. Low urgency docs clarification. Defer until author undrafts.

Generated by 🔧 PR Triage Agent · 113.5 AIC · ⌖ 13 AIC · ⊞ 5.5K · ◷