Survey Repo App-token NBCs: token-expiry race & App-install assumption documentation

[marcusrbrown]

From PR #3347 Fro Bot review (two non-blocking concerns, both deferred from the main fix).

1. Token-expiry race (defensive)

The Mint App token for privacy gate step in .github/workflows/survey-repo.yaml runs once at job start with no if: guard. The recheck step then runs much later (after the survey agent finishes, which can take up to the 30-min job timeout). App installation tokens live ~1h, so today's worst case is well within the lifetime. But if survey timeouts ever climb past ~50 minutes, the recheck step could race the token expiry and fail with a misleading 401.

Fix shape (when worth doing): re-mint the token immediately before the recheck step, or move the mint to a second dedicated step gated on the same condition as recheck. Today's envelope doesn't need it.

2. App-install assumption documentation (cosmetic)

Four workflows now depend on APPLICATION_ID/APPLICATION_PRIVATE_KEY being installed on github.repository_owner (= fro-bot): update-metadata.yaml, dispatch-renovate.yaml, reconcile-repos.yaml, survey-repo.yaml. The dependency is settled in practice but undocumented.

Fix shape: add a single comment block somewhere central — update-metadata.yaml is the natural home as it was the first cross-org App-token consumer — that documents the App-install precondition.

Why deferred

PR #3347 was focused on closing the bfra-me cross-org survey block. Both NBCs are forward-looking polish that doesn't affect today's correctness. Appropriate as a single bounded follow-up.

[fro-bot]

Both NBCs from #3347 confirmed against current main. Triaged together as a single bounded follow-up.

1. Token-expiry race — verified, accurately characterized

Mint App token for privacy gate lives at survey-repo.yaml:76-82, ungated and unconditional. The recheck step at survey-repo.yaml:213-235 reuses the same steps.gate-token.outputs.token after the survey agent runs. Job timeout is 30 minutes; installation tokens are ~1h. Today's envelope is safe.

The hazard is well-described: if survey timeouts climb past ~50 minutes, the recheck races expiry and emits a 401 disguised as a visibility-recheck failure (survey-repo.yaml:231 swallows stderr with 2>/dev/null, which would make the diagnostic even worse than the original problem #3344 surfaced).

Recommended fix shape: a second actions/create-github-app-token step gated on the same if: as the recheck (!cancelled() && steps.survey-agent.conclusion != 'skipped'), feeding a recheck-token into the recheck step's GH_TOKEN. Re-minting is cheaper than reasoning about expiry windows, and the gate is already on the right step. Don't reuse the gate-token id — the names matter for grep-ability when the next person debugs an auth failure here.

Stretch: while we're touching that block, drop 2>/dev/null from the recheck gh api call. The first-resolve step already learned this lesson (survey-repo.yaml:100-110 captures stderr to a temp file with markers). The recheck should match.

2. App-install documentation — scope is wider than the issue claims

Issue body lists 4 workflows. Actual count on main is 11:

dispatch-renovate.yaml    manage-cache.yaml      manage-issues.yaml
merge-data.yaml           reconcile-repos.yaml   renovate.yaml
reset-survey-status.yaml  survey-repo.yaml       update-metadata.yaml
update-repo-settings.yaml wiki-lint.yaml

update-metadata.yaml is still the right home for the canonical comment — it's the oldest cross-org App-token consumer in the repo and gets read first by anyone tracing the pattern. A single block documenting the APPLICATION_ID / APPLICATION_PRIVATE_KEY precondition on github.repository_owner (fro-bot), with a one-line list of dependent workflows, is enough. The other 10 callers can stay as-is; one source of truth beats eleven comment copies that will drift.

Proposed next steps

Single PR, two surgical commits:

1. survey-repo.yaml: add gated re-mint before recheck, attach to recheck step's GH_TOKEN, restore stderr capture on the recheck gh api.
2. update-metadata.yaml: prepend the App-install precondition comment block listing all 11 dependents.

Both are forward-looking polish, no behavioral change today. Happy to stage this on a branch when there's an opening.

---

Run Summary

Field	Value
Event	issues
Repository	fro-bot/.github
Run ID	26175200771
Cache	hit
Session	ses_1b9d3d17cffeggpD9vUQVGnHYL