addteam

Invite GitHub collaborators from a simple YAML file.

Install

pip install addteam

Or run without installing:

uvx addteam

Prerequisite: GitHub CLI must be installed and authenticated (gh auth login).

First Run

# In your repo directory, create a team.yaml
addteam --init

# Edit team.yaml with your team members, then run:
addteam

That's it! Your collaborators will be invited.

team.yaml Format

default_permission: push

admins:
  - alice

developers:
  - bob
  - username: charlie
    name: Charlie Day      # optional display name

reviewers:
  - eve

name: is optional anywhere a username: is given — it shows up in audit/apply output, --json, and addresses welcome issues by name.

Role names map to permissions automatically:

Unknown keys produce a warning (not silent drops), so a typo like develoeprs: won't quietly shrink your team.

Note: maintain and triage only exist on organization-owned repos. On personal repos addteam automatically degrades to push/pull with a warning (never expands access), so one config works everywhere.

Common Commands

addteam                    # invite from local team.yaml
addteam -n                 # dry-run (preview only)
addteam -a                 # audit (show drift)
addteam -s                 # sync (also removes unlisted users, asks first)
addteam --from org/config  # use team.yaml from another repo

Apply mode also fixes permission drift: if a collaborator exists with the wrong permission, it is updated to match team.yaml.

Central Team Config

Keep one team.yaml in a shared repo, apply it anywhere:

# Anyone on your team can run this in any repo:
uvx addteam --from myorg/team-config

(addteam myorg/team-config without --from still works and means the same thing; --from is the explicit, less ambiguous spelling. Confusing it with -r owner/repo — which selects the target repo — is a common mistake.)

Apply only one group (e.g. just the leads) to a specific repo:

uvx addteam --from myorg/team-config --group maintainers -r myorg/the-repo

The AI summary at the end is perfect for sharing via email or Slack.

Options

Exit codes: 0 success · 1 runtime error (or drift with --fail-on-drift) · 2 usage error.

Directory Report

Audit every repo in a folder at once:

addteam --report ~/dev
addteam --report ~/dev --csv access.csv --format matrix

Scans each subdirectory with a git working copy, collects collaborators (active and pending invitations) with permissions, looks up display names, shows a users × repos matrix in the terminal, and optionally writes a CSV spreadsheet. Also available as --json for scripting.

Scripting

addteam --audit --json | jq '.drift'
addteam --audit --fail-on-drift   # CI gate: fail the job on drift

GitOps Setup

Automatically sync collaborators when team.yaml changes:

addteam --init --init-action

This creates:

• team.yaml - your team config
• .github/workflows/sync-collaborators.yml - runs on push

Add a TEAM_SYNC_TOKEN secret (PAT with repo scope) to your repo.

Advanced Features

Expiring Access

contractors:
  - username: temp-dev
    permission: push
    expires: 2027-06-01

Expired users are skipped on apply and removed on --sync.

GitHub Teams (orgs)

teams:
  - myorg/backend-team
  - myorg/frontend-team: pull

If a team lookup fails, the affected members are skipped with a warning and --sync refuses to run — a partial config must never cause mass removals.

Multi-Repo Management

addteam --init-multi-repo

Creates repos.txt to sync the same team across multiple repos.

Welcome Issues

New collaborators automatically get a welcome issue with an AI-generated summary of your repo (requires OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, or OPENROUTER_API_KEY).

Welcome issues are on by default. Turn them off per run with --no-welcome, or per repo in config:

welcome_issue: false

License

MIT