Configure cross-repository credential for workflow automation

[vitormattos]

Parent: #11
Related: #12, #13

Context

The catalog publisher and consumer synchronizer need to:

• read/write branches in LibreCodeCoop/.github and managed consumer repositories;
• create/update pull requests across repositories.

The first real runs failed early because WORKFLOW_UPDATE_TOKEN is not configured in LibreCodeCoop/github-workflows.

Preferred credential model

Prefer a dedicated GitHub App installation credential over a personal access token when practical.

The credential should have only the permissions required for managed repositories, typically:

• Contents: read/write;
• Pull requests: read/write;
• Metadata: read.

Repository access should be limited to:

• LibreCodeCoop/.github;
• declared consumer repositories;
• additional repositories only when they are explicitly onboarded.

If a repository/organization secret named WORKFLOW_UPDATE_TOKEN is used initially, it must provide equivalent scoped access and must not be tied to a developer's everyday personal token.

Acceptance criteria

• the credential is available to LibreCodeCoop/github-workflows;
• catalog publication can checkout and open a PR in LibreCodeCoop/.github;
• consumer synchronization can checkout and open a PR in LibreCodeCoop/extract;
• no broader organization write access is granted than required;
• credential setup/rotation ownership is documented.

Validation

After configuration:

1. manually run Publish workflow catalog and confirm a no-op run creates no PR;
2. manually run Sync consumer workflows and confirm the initial extract adoption PR is created;
3. merge the adoption lock PR and run again to confirm no-op behavior.

Latest production validation

The blocker is still active as of 2026-09-20.

• scheduled Sync consumer workflows run 35502360899 failed at the Validate workflow update token preflight;
• the runner saw WORKFLOW_UPDATE_TOKEN as empty;
• the most recent Publish workflow catalog push run failed at the same preflight;
• no downstream checkout, mutation or partial publication occurred.

This confirms the current failure mode is intentional and fail-closed. There is no new workflow regression to fix before configuring the credential.

Next operational step

Configure the scoped cross-repository credential for LibreCodeCoop/github-workflows, then:

1. run Publish workflow catalog manually and confirm the current catalog produces no unexpected diff/PR;
2. make PR chore: manage validated extract workflows #27 ready and merge it;
3. run Sync consumer workflows and review the initial LibreCodeCoop/extract adoption/lock PR;
4. merge the adoption PR;
5. run synchronization again and confirm it is a no-op;
6. complete the two remaining real-target scenarios in Validate workflow update failure and recovery paths end to end #14 and the automation acceptance criteria in Automate workflow catalog publication to LibreCodeCoop/.github #12/Automate consumer workflow synchronization and update PRs #13.

Completed validation

The GitHub App path is now validated in production:

• App ID/private key are available to Actions;
• short-lived installation tokens are created successfully;
• each token is scoped to the exact destination repository;
• catalog publication can access LibreCodeCoop/.github;
• consumer synchronization can access LibreCodeCoop/extract;
• the first adoption PR was created by librecode-workflow-automation[bot];
• a subsequent sync with the complete lock produced no PR;
• setup, onboarding and private-key rotation are documented in
  docs/cross-repository-automation.md.

Implementation: #35
Documentation: #37