GitHub¶
URL Formats¶
| Format | Example |
|---|---|
| SSH | git@github.com:owner/repo.git |
| HTTPS | https://github.com/owner/repo.git |
Authentication¶
Personal Access Token (PAT)¶
The default authentication method:
Your token needs the repo scope to create PRs in target repositories, and the workflow scope to change files under .github/workflows/.
GitHub App (Recommended for Enterprise)¶
For organizations that prefer GitHub Apps over PATs, see GitHub App Authentication for:
- Verified commits (signed by GitHub)
- Fine-grained permissions
- Better audit trails
GitHub Enterprise Server¶
xfg supports GitHub Enterprise Server (GHE) instances in addition to github.com.
GHE URL Formats¶
| Format | Example |
|---|---|
| SSH | git@github.mycompany.com:owner/repo.git |
| HTTPS | https://github.mycompany.com/owner/repo.git |
Configuration¶
To use GHE repositories, add the hostname(s) to the githubHosts array in your config:
id: my-org-config
githubHosts:
- github.mycompany.com
- ghe.internal.net
files:
config.json:
content:
key: value
repos:
- git: git@github.mycompany.com:owner/repo.git
- git: https://ghe.internal.net/org/project.git
A GHE host that is not listed in githubHosts is detected as a self-hosted GitLab instance, so list every GHE host. See Platform Support.
GHE Authentication¶
Authenticate with each GHE instance using the --hostname flag:
xfg only hands GitHub credentials (App JWTs, installation tokens, GH_TOKEN) to github.com by default. githubHosts comes from the config file, so it can't grant that trust. List each GHE host in the XFG_ALLOWED_GITHUB_HOSTS environment variable as well:
In the GitHub Action, the allowed-github-hosts input sets this variable (comma-separated hostnames). See Action Inputs.
xfg fails every repo on a GHE host that isn't listed, before running any gh or git command against it. XFG_ALLOWED_GITHUB_HOSTS entries must be plain hostnames, with no scheme, port, path, userinfo or IP address. githubHosts entries must be plain hostnames, with no scheme, port, path or userinfo. A repo on an IP-address host fails the host check, because the variable cannot list an IP
address.
Mixed Environments¶
You can use github.com and GHE repositories in the same config file:
id: my-org-config
githubHosts:
- github.mycompany.com
files:
shared-config.json:
content:
version: "1.0"
repos:
# github.com (no config needed)
- git: git@github.com:myorg/public-repo.git
# GitHub Enterprise
- git: git@github.mycompany.com:myorg/private-repo.git
Required Permissions¶
Your token needs the repo scope to create PRs in target repositories, and the workflow scope to change files under .github/workflows/.
Auto-Merge¶
GitHub's auto-merge feature requires it to be enabled in the repository settings.
Check if enabled:
Enable it:
If auto-merge is not enabled, xfg will warn and leave the PR open for manual review.
PR Creation¶
xfg uses the gh CLI to:
- Create the PR with
gh pr create - Enable auto-merge with
gh pr merge --auto(if configured) - Force merge with
gh pr merge --admin(ifmerge: force)
Direct Push Mode¶
With merge: direct, xfg skips PR creation entirely and pushes directly to the default branch:
id: my-org-config
files:
.prettierrc.json:
content:
semi: false
prOptions:
merge: direct
repos:
- git: git@github.com:org/internal-tool.git
This is useful for repos without branch protection or when PR review isn't required. If the branch is protected, the push will fail with a helpful error suggesting to use merge: force instead.
When to use direct vs force:
direct: Repo has no branch protection, or you want to skip PR workflow entirelyforce: Repo has branch protection, but you have admin privileges to bypass it (creates a PR and merges with--admin)
GitHub Rulesets¶
The xfg sync command manages GitHub Rulesets declaratively. See GitHub Rulesets for full documentation.
settings:
rulesets:
main-protection:
target: branch
enforcement: active
conditions:
refName:
include: [refs/heads/main]
rules:
- type: pull_request
parameters:
requiredApprovingReviewCount: 1
Required Permissions for Rulesets¶
Managing rulesets requires admin access to the repository. Your token needs:
- PAT: the
reposcope (classic) or the "Administration" repository permission set to "Read and write" (fine-grained) - GitHub App: "Administration" permission set to "Read and write"
Rulesets vs Branch Protection¶
GitHub Rulesets are the modern replacement for branch protection rules. They offer:
- Pattern-based conditions (apply to multiple branches)
- Multiple rules per ruleset
- Bypass actors with fine-grained control
- Evaluate mode for testing
- Advanced rules (code scanning, workflows, file restrictions)
xfg uses the Rulesets API exclusively. If you need legacy branch protection rules, you'll need to manage those separately.
GitHub Labels¶
The xfg sync command can manage GitHub labels declaratively. See GitHub Labels for full documentation.