Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 

Repository files navigation

Cross-organization repository branch sync

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.

Naming behavior

Set the configuration variable DESTINATION_PREFIX to an organization-wide prefix such as ast-.

  • acme becomes ast-acme when destination_repo is omitted.
  • Set destination_repo for an exact per-repository override. An explicit override bypasses the global prefix.

Security architecture

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.

Repository variables

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.

Environment secrets

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.

Configuration schema

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

Synchronization semantics

  • 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.

Composite-action bootstrap note

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.

Recommended hardening

  • 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-sync environment.
  • Rotate both PATs regularly and update the environment secrets before their configured expiration.
  • Review destination organization rulesets before enabling force synchronization.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors