This project copies one selected branch from each configured source repository into a destination organization. It creates a destination repository when absent and otherwise updates the configured destination branch while preserving the complete Git history reachable from the selected source branch.
Set the configuration variable DESTINATION_PREFIX to an organization-wide prefix such as ast-.
acmebecomesast-acmewhendestination_repois omitted.- Set
destination_repofor an exact per-repository override. An explicit override bypasses the global prefix.
Use two personal access tokens (PATs), one for each organization. Fine-grained PATs are recommended because each token can be limited to one resource owner, selected repositories, and explicit permissions. The workflow reads both PATs from the protected repository-sync environment and does not mint or exchange credentials at runtime.
| Secret | Fine-grained PAT resource access | Repository permissions | Used for |
|---|---|---|---|
SOURCE_PAT |
Source organization; only configured source repositories | Contents: read (Metadata: read is included) | Clone and LFS reads |
DESTINATION_PAT |
Destination organization; all repositories | Administration: write, Contents: write, and Workflows: write only when copied branches contain .github/workflows |
Repository lookup/creation, branch pushes, and LFS writes |
The destination token needs All repositories access so it can create and immediately push to repositories that do not exist when the token is issued. The PAT owner must be a member of the destination organization and must be allowed to create repositories; token permissions cannot exceed the owner's access. If every destination repository already exists and automatic creation is not required, the destination PAT can instead be limited to those repositories and the creation step can be removed.
The destination organization may require approval for fine-grained PATs. Approve both tokens before running the workflow and configure an expiration and rotation process. See GitHub's documentation for creating fine-grained PATs, PAT organization policies, and repository creation permissions.
Classic PATs can be used when fine-grained PATs are unavailable. They require the broad repo scope for private repositories, and the destination PAT also requires workflow when copied branches contain workflow files. Authorize classic PATs for SAML SSO when either organization requires it.
Create these variables in the orchestration repository or in the repository-sync environment:
SOURCE_ORG=source-organization
DESTINATION_ORG=destination-organization
DESTINATION_PREFIX=ast-
Both workflow jobs declare the repository-sync environment so environment-level variables are available before the repository matrix is generated. If the environment has required reviewers, approval is therefore requested before matrix generation. An explicit destination_repo remains an exact-name override and does not receive the prefix.
Create a protected environment named repository-sync, then add:
SOURCE_PAT
DESTINATION_PAT
Store each complete PAT value. Add required reviewers to the environment when repository creation or force synchronization should require approval.
config/repositories.json contains global defaults and repository mappings.
{
"defaults": {
"source_branch": "main",
"visibility": "private",
"force_push": true,
"include_lfs": true
},
"repositories": [
{
"source_repo": "acme"
},
{
"source_repo": "payment-service",
"source_branch": "release/federal",
"destination_repo": "ast-payments",
"destination_branch": "main"
}
]
}Supported repository fields:
| Field | Purpose |
|---|---|
source_repo |
Required source repository name |
source_branch |
Source branch; defaults to defaults.source_branch |
destination_repo |
Exact destination name; otherwise prefix + source name |
destination_branch |
Target branch; defaults to source branch |
visibility |
private, internal, or public; used only on creation |
description |
Used only on creation |
force_push |
Exact-copy mode using force-with-lease; defaults to true |
include_lfs |
Copies LFS objects reachable from the selected branch |
enabled |
Set false to omit the entry from the matrix |
- Only the configured branch is copied; tags and unrelated branches are not copied.
- Full Git history reachable from that branch is retained because the clone is not shallow.
- Exact-copy mode uses
--force-with-lease, not an unconditional force push. The job fails if another writer changes the destination after the destination SHA is read. - Existing repository settings, issues, pull requests, releases, and other branches are not modified.
- A destination branch protection rule or ruleset can reject the update. Configure a bypass for the PAT owner's identity or team only where the rule type supports it and organizational policy permits it.
- PATs are used as supplied and are not refreshed during a run. Update the environment secrets before the tokens expire or are revoked.
All synchronization logic is implemented in local composite actions. GitHub must first download the orchestration repository before local actions can be resolved, so each job has one actions/checkout bootstrap step. To make literally every workflow step a composite action, publish these composites in a separate trusted actions repository and reference that repository by immutable commit SHA.
- Pin third-party and GitHub-maintained actions to reviewed full commit SHAs in production.
- Use dedicated automation identities with no access beyond the repositories and organization capabilities needed by this workflow.
- Permit only manual dispatch or another trusted trigger; do not expose PATs to pull-request workflows.
- Protect the orchestration repository, configuration file, workflow, and composite-action paths with CODEOWNERS and branch rules.
- Restrict who can approve the
repository-syncenvironment. - Rotate both PATs regularly and update the environment secrets before their configured expiration.
- Review destination organization rulesets before enabling force synchronization.