Skip to content

Repo Lifecycle Management

xfg can automatically create, fork, or migrate repositories before syncing files or applying settings. This is useful when managing repos declaratively - if a target repo doesn't exist yet, xfg will create it for you.

How It Works

Before processing each repo, xfg checks if the target repository exists:

  1. Exists - Proceed normally with sync/settings
  2. Missing - Create an empty repo
  3. Missing + upstream - Fork from the upstream repo
  4. Missing + source - Clone source with --mirror and push to new target

Fields

Field Type Description
upstream string Git URL of repo to fork from (GitHub only)
source string Git URL of repo to migrate from (e.g., Azure DevOps to GitHub)

Mutually exclusive

upstream and source cannot be used together on the same repo. Use upstream for forking within GitHub, or source for cross-platform migration.

Forking is GitHub-only

Both the upstream and target repos must be on GitHub (or GitHub Enterprise). Cross-platform forking is not supported. For cross-platform transfers, use source (migration) instead.

Forking (upstream)

Fork an existing repo into your organization or personal account:

id: lifecycle
files:
  .prettierrc.json:
    content: { semi: false }

repos:
  # Fork into an organization
  - git: git@github.com:my-org/forked-tool.git
    upstream: git@github.com:opensource/cool-tool.git

  # Fork into a personal account
  - git: git@github.com:myusername/my-fork.git
    upstream: git@github.com:opensource/cool-tool.git

When the target repo doesn't exist, xfg will:

  1. Detect whether the target owner is an organization or user
  2. Fork the upstream repo accordingly
  3. Continue with normal sync/settings

If the repo already exists, the upstream field is ignored.

Git array expansion

When using a git array with upstream, the same upstream is applied to all expanded repos:

id: lifecycle
files:
  .prettierrc.json:
    content: { semi: false }

repos:
  - git:
      - git@github.com:my-org/fork-a.git
      - git@github.com:my-org/fork-b.git
    upstream: git@github.com:opensource/tool.git

This creates two forks of opensource/tool with different names (fork-a and fork-b).

Fork settings

After forking, xfg will apply settings.repo.visibility and settings.repo.description if configured. This allows you to fork a public repo and make it private, or vice versa.

Migration (source)

Migrate a repo from another platform (e.g., Azure DevOps to GitHub):

id: lifecycle
files:
  .prettierrc.json:
    content: { semi: false }

repos:
  - git: git@github.com:my-org/migrated-app.git
    source: https://dev.azure.com/myorg/myproject/_git/legacy-app

When my-org/migrated-app doesn't exist, xfg will:

  1. Clone legacy-app from Azure DevOps with --mirror (all branches and tags)
  2. Create migrated-app on GitHub
  3. Push the mirrored content to the new repo
  4. Clean up the temporary clone
  5. Continue with normal sync/settings

If the repo already exists, the source field is ignored.

Creation Settings

When creating a new repo (via create, fork, or migrate), xfg applies the repo's merged settings.repo (root, groups, and per-repo settings combined). A per-repo repo: false skips them. Repos are created as private by default. Set visibility: public explicitly if needed.

id: lifecycle
settings:
  repo:
    description: "My new repository"
    visibility: private
    hasIssues: true
    hasWiki: false

repos:
  - git: git@github.com:my-org/new-repo.git
    # No upstream or source = create empty repo with above settings

The following settings apply during repo creation:

Setting Description
description Repository description
visibility public, private, or internal
hasIssues Enable/disable Issues (default: enabled)
hasWiki Enable/disable Wiki (default: enabled)
defaultBranch Rename the default branch during creation or migration

Default Branch Renaming

When settings.repo.defaultBranch is set, xfg renames the default branch during lifecycle operations:

Operation Behaviour
Create After creating the repo, detects the actual branch name and renames it via the GitHub API
Migrate Before pushing the mirror clone, renames the source HEAD branch in git
Fork Ignored — forked repos inherit the upstream's branch structure
Settings Updates the GitHub API pointer (the branch must exist)
# Migrate ADO repo with 'master', rename to 'main' on GitHub
id: lifecycle
repos:
  - git: git@github.com:my-org/migrated-app.git
    source: https://dev.azure.com/myorg/myproject/_git/legacy-app
    settings:
      repo:
        defaultBranch: main

Empty Repository Initialization

When creating a new repository, xfg uses --add-readme to establish the default branch with an initial commit, then immediately deletes the README to leave the repo in a clean state. This ensures subsequent clone and push operations work correctly, since empty repositories without any commits have no resolvable HEAD.

Mirror Clone Cleanup

When migrating with source, the mirror clone may include platform-specific refs that GitHub rejects on push (such as refs/pull/* from GitHub, refs/merge-requests/* from GitLab, or other internal refs). xfg automatically strips all refs except branches (refs/heads/*) and tags (refs/tags/*) before pushing to the target repository.

Dry Run

In dry-run mode (--dry-run), lifecycle operations are reported but not executed:

+ CREATE my-org/new-repo
+ FORK git@github.com:opensource/cool-tool.git -> my-org/forked-tool
+ MIGRATE https://dev.azure.com/myorg/myproject/_git/legacy-app -> my-org/migrated-app

Plan: 3 repos (1 to create, 1 to fork, 1 to migrate)

FORK and MIGRATE lines show the upstream or source URL exactly as written in the config.

Supported Platforms

Operation GitHub Azure DevOps GitLab
Create (target) Yes - -
Fork (target) Yes - -
Migrate (target) Yes - -
Migrate (source) - Yes -

Authentication

Create, fork, and migrate work with both auth types, for organizations and personal accounts:

Target owner PAT (GH_TOKEN) GitHub App installation token
Organization Yes Yes
Personal account Yes Yes

A GitHub App needs these permissions on top of the base set:

Operation GitHub App permissions
Create Repository creation: Read and write
Migrate (target) Repository creation: Read and write
Fork Repository creation: Read and write, Administration: Read and write, Contents: Read

To fork, GitHub also needs the App installed on the target account with access to all its repositories, and on the upstream account with access to the upstream repo.

After you change an App's permissions, the account owner must approve them on each installation before new tokens get them.

GitHub sometimes reports a missing App permission as HTTP 403: Rate Limit Exceeded. When an App token gets a 403 on create, fork, or migrate, xfg stops at once and names the permissions above instead of retrying. Real rate limits are still retried. --dry-run does not check permissions.

The Actions GITHUB_TOKEN can't be given these permissions, so it can't create, fork, or migrate repos. Use a GitHub App or a PAT.

Example: Full Lifecycle Config

id: my-org-repos

settings:
  repo:
    visibility: private
    hasWiki: false
    deleteBranchOnMerge: true

files:
  .gitignore:
    content: |
      node_modules/
      dist/

repos:
  # Existing repo - just sync files
  - git: git@github.com:my-org/existing-service.git

  # Fork an open-source tool
  - git: git@github.com:my-org/our-eslint-config.git
    upstream: git@github.com:airbnb/javascript.git

  # Migrate from Azure DevOps
  - git: git@github.com:my-org/migrated-api.git
    source: https://dev.azure.com/myorg/legacy/_git/old-api