GitHub Collaborators¶
xfg can add direct collaborators to personal (user-owned) GitHub repos with the sync command. Use it to make sure a bot account (for example, a CI or ops bot) has access to every repo you manage.
Personal repos only
Collaborators only apply to repos owned by a user account. Repos owned by an organization are skipped with a warning. Azure DevOps and GitLab repos are skipped.
Quick Start¶
id: my-config
settings:
collaborators:
users:
- my-bot
repos:
- git: git@github.com:your-user/your-repo.git
# Preview changes (dry-run)
xfg sync -c config.yaml --dry-run
# Send invites
xfg sync -c config.yaml
How Invites Work¶
GitHub does not add people to a personal repo straight away. It sends an invite that the user must accept.
- A user who is not a collaborator gets an invite (
PUT /repos/{owner}/{repo}/collaborators/{user}). - A user with a pending invite is left alone and shown as
invite pending. xfg does not send it again. - An expired invite is cancelled and sent again.
- A user who is already a collaborator is left alone.
Personal repos have no permission levels. Collaborators always get write access, so there is no permission field.
Inheritance¶
A plain users list replaces the inherited one. Use $arrayMerge: append to add to the inherited users instead. Names are matched without caring about case, and a repeated name is dropped, first spelling wins.
id: collaborators
settings:
collaborators:
users:
- my-bot
repos:
- git: git@github.com:your-user/foo.git
settings:
collaborators:
users:
$arrayMerge: append # effective: my-bot + other-bot
$values: [other-bot]
- git: git@github.com:your-user/baz.git
settings:
collaborators:
users: [other-bot] # replaces: other-bot only
- git: git@github.com:your-user/bar.git
settings:
collaborators:
inherit: false # drop inherited users
users: [only-this-one]
With deleteOrphaned: true, a plain list in a repo removes the inherited users from that repo. inherit: false also drops an inherited deleteOrphaned, so set it again in the same layer to keep cleanup on.
inherit is allowed in repos, groups, and conditional groups. It is not allowed at root.
Removing Collaborators¶
By default xfg never removes anyone. Turn on deleteOrphaned and the users list becomes the full list: anyone else is removed.
- Direct collaborators not in
usersare removed, including people added by hand. - Pending invites for people not in
usersare cancelled. - The repo owner is never removed.
--no-deleteturns off removal for that run.
Warning
With deleteOrphaned: true, an empty or missing users list removes every collaborator except the owner.
Dry Run Output¶
your-user/foo - Collaborators:
Invite:
+ collaborator "other-bot" (invite)
Remove:
- collaborator "old-bot"
collaborator "my-bot": invite pending
Plan: 2 collaborators (1 to invite, 1 to remove)
GitHub API Reference¶
Collaborators are managed via the GitHub Collaborators API:
GET /repos/{owner}/{repo}/collaborators?affiliation=direct— List direct collaboratorsGET /repos/{owner}/{repo}/invitations— List pending invitesPUT /repos/{owner}/{repo}/collaborators/{username}— Invite a userDELETE /repos/{owner}/{repo}/collaborators/{username}— Remove a collaboratorDELETE /repos/{owner}/{repo}/invitations/{invitation_id}— Cancel an invite