gh-team-kit

README

gh-team-kit

gh extension of github team api

Installation

To install the tool, you can use the following command:

gh extension install srz-zumix/gh-team-kit

Shell Completion

Workaround Available! While gh CLI doesn't natively support extension completion, we provide a patch script that enables it.

Prerequisites: Before setting up gh-team-kit completion, ensure gh CLI completion is configured for your shell. See gh completion documentation for setup instructions.

For detailed installation instructions and setup for each shell, see the Shell Completion Guide.

Commands Overview

The following commands are available in gh-team-kit. Each command is designed to help manage GitHub teams, repositories, and users efficiently.

• Team Management: Create, update, delete, move, and display team hierarchies.
• Configuration Management: Export and import team information for backup and bulk operations.
• Member Management: Add, remove, check, and modify roles of team members.
• Repository Management: Add, remove, list, and compare repositories associated with teams.
• User Management: Add, remove, list, and check users in the organization or repositories.
• Organization-Role Management: Manage roles within the organization, including listing available roles.
• Code Review Management: Get and set code review assignment settings for teams.
• IDP Management: Manage IDP groups (SAML team sync) and external groups (Enterprise Managed Users).
• Mannequin Management: List and reattribute mannequins (placeholder accounts for unclaimed users), individually or in bulk via a user mapping file.
• Permission Management: Check and synchronize permissions for teams and users across repositories.
• Comparison Tools: Compare teams, repositories, and permissions to identify differences.

Refer to the specific command sections below for detailed usage and examples.

Usage

Global Options

Read-Only Mode

gh team-kit <command> --read-only

Run any command in read-only mode to prevent write operations. This option is useful for safely testing commands or verifying what changes would be made without actually applying them. When enabled, all API calls that would modify data (create, update, delete operations) will be blocked.

Example:

# Test member addition without actually adding
gh team-kit member add my-team username --read-only

# Verify import operations without applying changes
gh team-kit --read-only import config.yaml

Shell Completion Commands

Generate shell completion script

gh team-kit completion -s <shell>

Generate shell completion patch for gh-team-kit. This patches gh's existing completion system to support the extension.

Flags:

• -s, --shell string: Shell type: {bash|zsh|fish|powershell}

Prerequisites: gh completion must be configured first. See gh completion documentation.

Examples:

# Bash
eval "$(gh team-kit completion -s bash)"

# PowerShell (load gh completion first)
Invoke-Expression $(gh completion -s powershell | Out-String)
Invoke-Expression $(gh team-kit completion -s powershell | Out-String)

For detailed setup instructions, see the Shell Completion guide in go-gh-extension.

Team Management

Create a new team

gh team-kit create <name> --description <description> --parent <parent-team-slug>

Create a new team in the specified organization with various options such as description, privacy, and notification settings.

Delete a team

gh team-kit delete <team-slug>

Delete a specified team from the organization. Ensure that the team is no longer needed as this action is irreversible.

Display a team hierarchy in a tree structure

gh team-kit tree [team-slug]

Display a team hierarchy in a tree structure based on the team's slug.

Get a team by its slug

gh team-kit get [team-slug...]

Retrieve details of a team using the team's slug.

List all teams in the organization

gh team-kit list [owner]

Retrieve and display a list of all teams in the specified organization. You can optionally filter the results by repository.

Move a team to a new parent

gh team-kit move <team-slug> [new-parent-slug]

Change the parent of an existing team in the specified organization to a new parent team. If no new parent is specified, the team will be moved to the root level.

Rename an existing team

gh team-kit rename <team-slug> <new-name>

Rename an existing team in the specified organization to a new name.

Update a team

gh team-kit update <team-slug> --description <new-description> --parent <parent-team-slug>

Update the details of an existing team in the specified organization, such as its description or settings.

Member Management

Add a member to a team

gh team-kit member add <team-slug> <username...> [role]

Add a specified user to the specified team in the organization. Optionally specify the role (default: member).

Check if a user is a member of a team

gh team-kit member check <team-slug> <username>

Check if a user is a member of a team.

Change the role of a user in a team

gh team-kit member role <team-slug> <username> <role>

Change the role of a specified user in the specified team. Valid roles are: member, maintainer.

List members of a team

gh team-kit member list <team-slug>

List all members of the specified team in the organization.

Randomly pick members from a team

gh team-kit member pick <team-slug> [count]

Randomly select a specified number of members from the team. If count is 0 (default), all members are returned. If count is negative, it picks (total members - |count|) members.

Perform set operations on two teams members

gh team-kit member sets <[[HOST/]OWNER/]team-slug1> <|,&,-,^> <[[HOST/]OWNER/]team-slug2>

Perform set operations on the members of two teams. The operation can be union (|), intersection (&), difference (-), or symmetric difference (^).

Sync members from one team to another

gh team-kit member sync <[[HOST/]OWNER/]src-team-slug> <[[HOST/]OWNER/]dst-team-slug>

Sync members from the source team to the destination team. Members in the source team will be added to the destination team, and members not in the source team will be removed from the destination team.

Copy members from one team to another

gh team-kit member copy <[[HOST/]OWNER/]src-team-slug> <[[HOST/]OWNER/]dst-team-slug>

Copy members from the source team to the destination team. Members in the source team will be added to the destination team, but no members will be removed from the destination team.

Remove a member from a team

gh team-kit member remove <team-slug> <username...>

Remove a specified user from the specified team in the organization.

Repository Management

Add a repository to a team

gh team-kit repo add <team-slug> <permission>

Add a specified repository to the specified team in the organization.

Check team permissions for a repository

gh team-kit repo check <team-slug>

Checks whether a team has admin, push, maintain, triage, pull, or none permission for a repository.

Compare repositories between two teams

gh team-kit diff <team-slug1> <team-slug2> [repository...]

Compare the repositories associated with two teams and display the differences.

Compare team permissions between two repositories

gh team-kit repo diff <repo1> <repo2> [team-slug...]

Compare the team permissions between two repositories and display the differences.

Copy teams and permissions to multiple destination repos

gh team-kit repo copy <dst-repository...>

Copy teams and permissions from a source repository to multiple destination repositories.

List repositories for a team

gh team-kit repo list <team-slug>

List all repositories for the specified team in the organization.

Remove a repository from a team

gh team-kit repo remove <team-slug>

Remove a specified repository from the specified team in the organization.

Sync teams and permissions to multiple destination repos

gh team-kit repo sync <dst-repository...>

Synchronize teams and permissions from a source repository to multiple destination repositories.

User Management

Add a user to the organization

gh team-kit user add <username>

Add a specified user to the organization.

Check the role of a user in the organization

gh team-kit user check <username>

Check the role of a specified user in the organization.

Import users into the organization

gh team-kit user import <input> [--owner <[HOST/]OWNER>] [--role <member|admin>] [--usermap <file>] [--dryrun]

Read a JSON list of users (as produced by user list --format json) and add each user to the organization. Each entry must have a login field. The role is taken from the role_name field if present; otherwise --role is used as the default (member). When --usermap is specified, source logins are resolved using the mapping file (as produced by user map). The src field supports regular expressions and dst may contain $N or ${name} capture-group references. Specify - as <input> to read from stdin.

Flag	Default	Description
--owner <[HOST/]OWNER>	(current repo owner)	Organization ([HOST/]OWNER)
--role <member|admin>	member	Default role when not specified in input
--usermap <file>	—	User mapping file for login conversion during import
--dryrun, -n	false	Dry run: show count without applying changes

Create a user mapping file between source and target organizations

gh team-kit user map <target> [--owner <[HOST/]OWNER>] [--output <file>] [--all] [--no-suspended] [--format <json|yaml>]

Generate a YAML mapping file that correlates users by their public email between a source organization (--owner) and a target organization (positional argument). Both --owner and <target> accept the [HOST/]OWNER format to specify a host. This mapping can be used with user import --usermap or import --usermap to automatically convert source logins to target logins. The src field in the output supports regular expressions and dst may contain $N or ${name} capture-group references when hand-edited. --output and --format are mutually exclusive.

Mapping file format:

users:
  - src: user1
    dst: target_user1
    email: user1@example.com

Flag	Default	Description
--owner <[HOST/]OWNER>	(current repo owner)	Source organization
--output <file>, -o	—	Write mapping YAML to file; if omitted, output goes to stdout using --format (default: table)
--all, -a	false	Include source users with no email match (dst will be empty)
--emu	false	Compact matched pairs sharing the same base login into a single regex entry. Supports: both logins have a slug (alice_corp→alice_new ⇒ (.+)_corp→$1_new), src-only slug (alice_corp→alice ⇒ (.+)_corp→$1), dst-only slug (alice→alice_new ⇒ (.+)→$1_new). Pairs whose base names differ or have an empty dst are kept as exact entries.
--no-suspended	false	Exclude suspended users from source and target before matching
--quiet	false	Suppress warnings for source users with no matching target user
--format <json|yaml>	—	Output format: json or yaml (mutually exclusive with --output)

List all users in the organization

gh team-kit user list

Retrieve and display a list of all users in the organization.

List user repositories

gh team-kit user repos [username]

Retrieve and display a list of repositories that a specified user has access to, including their roles and permissions.

Remove a user from the organization

gh team-kit user remove <username>

Remove a specified user from the organization.

Change the role of a user in a orgnization

gh team-kit user role <username> <role>

Change the role of a specified user in the organization. Valid roles include member and admin.

Search GitHub users

gh team-kit user search <query>

Search for GitHub users by query string.

Get contextual hovercard information for a user

# Basic hovercard
gh team-kit user hovercard get <username>

# Issue hovercard
gh team-kit user hovercard issue <username> <issue-number>

# Organization hovercard
gh team-kit user hovercard org <username> <org>

# Pull request hovercard
gh team-kit user hovercard pr <username> <pr-number>

# Repository hovercard
gh team-kit user hovercard repo <username> <repo>

Retrieve contextual hovercard information for a user. Use each subcommand for different contexts (basic, issue, organization, pull request, repository).

Add a user as a collaborator to a repository

gh team-kit repo user add <username> <permission>

Add a specified user as a collaborator to a repository with a given permission (admin, maintain, push, triage, pull).

Check user permissions for a repository

gh team-kit repo user check <username>

Check the permissions of a specified user for a repository.

List users with access to a repository

gh team-kit repo user list

List all collaborators for the specified repository. You can filter the results by affiliation and role.

Remove a user's access to a repository

gh team-kit repo user remove <username>

Remove a specified user's access to a repository.

Member Privileges Management

Get or set the default repository permission (base permissions)

gh team-kit member-privilege base-permissions [--set <read|write|admin|none>] [--owner <[HOST/]OWNER>]

Get or set the default repository permission for organization members. When --set is specified, the setting is updated and the result is displayed; otherwise the current value is displayed.

Flag	Default	Description
--set <read|write|admin|none>	—	New value to set. Omit to get the current value.
--owner <[HOST/]OWNER>	(current repo owner)	Organization ([HOST/]OWNER)

Get or set whether members can create teams

gh team-kit member-privilege can-create-teams [--set[=false]] [--owner <[HOST/]OWNER>]

Get or set whether organization members can create teams. When --set is specified, the setting is updated and the result is displayed; otherwise the current value is displayed.

Flag	Default	Description
--set	—	Allow members to create teams. Use --set=false to disallow. Omit to get the current value.
--owner <[HOST/]OWNER>	(current repo owner)	Organization ([HOST/]OWNER)

Copy member privileges from one organization to another

gh team-kit member-privilege copy <src-owner> <dst-owner>

Copy all member privileges settings from the source organization to the destination organization.

Get member privileges of an organization

gh team-kit member-privilege get [--owner <[HOST/]OWNER>] [--fields <fields>]

Get the member privileges settings of the specified organization. Displays a table with fields such as default repository permission, repository creation, forking, pages, team creation, and web commit signoff settings.

Flag	Default	Description
--owner <[HOST/]OWNER>	(current repo owner)	Organization ([HOST/]OWNER)
--fields <fields>	(all fields)	Comma-separated list of fields to display

Set member privileges of an organization

gh team-kit member-privilege set [flags]

Update one or more member privileges settings of the specified organization. Only the flags explicitly specified will be changed.

Flag	Default	Description
--owner <[HOST/]OWNER>	(current repo owner)	Organization ([HOST/]OWNER)
--default-repo-permission <read|write|admin|none>	—	Default repository permission for organization members
--members-can-create-repos / --no-members-can-create-repos	—	Allow or disallow members to create repositories
--members-can-create-public-repos / --no-members-can-create-public-repos	—	Allow or disallow members to create public repositories
--members-can-create-private-repos / --no-members-can-create-private-repos	—	Allow or disallow members to create private repositories
--members-can-create-internal-repos / --no-members-can-create-internal-repos	—	Allow or disallow members to create internal repositories
--members-can-fork-private-repos / --no-members-can-fork-private-repos	—	Allow or disallow members to fork private repositories
--members-can-create-pages / --no-members-can-create-pages	—	Allow or disallow members to create GitHub Pages sites
--members-can-create-public-pages / --no-members-can-create-public-pages	—	Allow or disallow members to create public GitHub Pages sites
--members-can-create-private-pages / --no-members-can-create-private-pages	—	Allow or disallow members to create private GitHub Pages sites
--members-can-create-teams / --no-members-can-create-teams	—	Allow or disallow members to create teams
--web-commit-signoff-required / --no-web-commit-signoff-required	—	Require or disable web commit signoff

Organization-Role Management

List teams assigned to an organization role

gh team-kit org-role team list <org-role>

Retrieve and display a list of all teams assigned to a specific role in the organization.

Add a team to an organization role

gh team-kit org-role team add <team-slug> <org-role>

Add a specified team to the specified role in the organization.

Remove a team from an organization role

gh team-kit org-role team remove <team-slug> <org-role>

Remove a specified team from the specified role in the organization.

Import custom organization roles

gh team-kit org-role import <input> [--owner <[HOST/]OWNER>] [--dryrun]

Read a JSON list of custom organization roles (as produced by org-role list --format json) and create or update each role in the organization. Only Organization-sourced (user-defined) roles are applied; Predefined and System roles are skipped. Specify - as <input> to read from stdin.

Flag	Default	Description
--owner <[HOST/]OWNER>	(current repo owner)	Organization ([HOST/]OWNER)
--dryrun, -n	false	Dry run: show count without applying changes

List organization roles

gh team-kit org-role list [owner] [--source <Organization|Predefined|System>] [--field <field>] [--name-only] [--format json]

List all roles available in the organization. Use --source to filter by role source (can be specified multiple times). Use --field to select columns to display (valid fields: ID, NAME, DESCRIPTION, BASE_ROLE, SOURCE, PERMISSIONS, CREATED_AT, UPDATED_AT). Use --name-only to output only role names.

List users assigned to an organization role

gh team-kit org-role user list [org-role-name]

Retrieve and display a list of all users assigned to a specific role in the organization. Supports options for detailed information, suspended users, and filtering by owner.

Add a user to an organization role

gh team-kit org-role user add <username> <org-role>

Assign a specified user to the specified role in the organization.

Remove a user from an organization role

gh team-kit org-role user remove <username> <org-role>

Remove a specified user from the specified role in the organization.

Mannequin Management

List mannequins in the organization

gh team-kit mannequin list [owner] [--name-only] [--format json] [--jq <expression>] [--template <string>]

List all mannequins (placeholder accounts for unclaimed users) in the specified organization. Use --name-only to output only login names. Use --format json with --jq or --template to customize JSON output.

Bulk-migrate mannequins using a user mapping file

gh team-kit mannequin migrate --usermap <file> [--owner <[HOST/]OWNER>] [--skip-invitation] [--force] [--dryrun]

List all mannequins in the organization and reattribute each one to its mapped target user. The mapping file (--usermap) must be a YAML file as produced by user map. Each mannequin is matched first by src login (supports regular expressions), then by email. Mannequins already claimed are skipped unless --force is specified. Entries whose dst is empty are skipped.

Flag	Default	Description
--usermap <file>	—	User mapping file (required)
--owner <[HOST/]OWNER>	(current repo owner)	Target organization
--skip-invitation	false	Skip invitation and directly reclaim (requires GitHub Support enablement)
--force	false	Process mannequins that are already claimed
--dryrun, -n	false	Show what would be done without making changes

Reattribute a mannequin by email

gh team-kit mannequin reattribute-by-email <email> [--owner <[HOST/]OWNER>] [--repo [HOST/]OWNER/REPO] [--usermap <file>] [--skip-invitation] [--force]

Find the mannequin and target user by email, then send an attribution invitation. Without --usermap, both are resolved by searching their email within the target organization. With --usermap, the mannequin login (src) and target user login (dst) are read directly from the mapping file using the email as key.

Flag	Default	Description
--owner <[HOST/]OWNER>	(current repo owner)	Target organization
--repo [HOST/]OWNER/REPO, -R	—	Target repository (alternative to --owner)
--usermap <file>	—	Resolve logins from mapping file instead of searching by email
--skip-invitation	false	Skip invitation and directly reclaim (requires GitHub Support enablement)
--force	false	Proceed even if mannequin is already claimed

Reattribute a mannequin to a user

gh team-kit mannequin reattribute <mannequin-login> <target-user-login> [--owner <[HOST/]OWNER>] [--skip-invitation] [--force]

Send an attribution invitation to a user to claim the specified mannequin. The target user must be a member of the organization. Use --skip-invitation to skip the invitation step and directly reclaim the mannequin (requires the feature to be enabled by GitHub Support).

Flag	Default	Description
--owner <[HOST/]OWNER>	(current repo owner)	Organization ([HOST/]OWNER)
--skip-invitation	false	Skip invitation and directly reclaim (requires GitHub Support enablement)
--force	false	Proceed even if mannequin is already claimed

IDP Management

Connect an external group to a team

gh team-kit idp emu set <group-name> <team-slug> [--owner <[HOST/]OWNER>] [--field <field>] [--format <json|table>]

Connect an external group to a team in the organization (Enterprise Managed Users). Resolves the group by name and connects it to the specified team. Use --field to display specific fields (ID, NAME, UPDATED_AT, TEAM_COUNT, MEMBER_COUNT). On success, prints a confirmation message unless --field or --format is used.

Find the external group connected to a team

gh team-kit idp emu find <team-slug> [--owner <[HOST/]OWNER>] [--field <field>] [--format <json|table>]

Find the external group connected to a team in the organization (Enterprise Managed Users). Exits with no output if no external group is connected (e.g. the team has explicit members). Available fields: ID, NAME, UPDATED_AT, TEAM_COUNT, MEMBER_COUNT.

Get an external group

gh team-kit idp emu get <group-name> [--owner <[HOST/]OWNER>] [--field <field>] [--format <json|table>]

Get details of a single external group by name in the organization (Enterprise Managed Users). Available fields: ID, NAME, UPDATED_AT, TEAM_COUNT, MEMBER_COUNT.

List external groups in the organization or connected to a team

gh team-kit idp emu list [team-slug] [--owner <[HOST/]OWNER>] [--query <name-filter>] [--details] [--field <field>] [--format <json|table>]

List all external groups available in the organization, or list external groups connected to the specified team (Enterprise Managed Users). Use --query to filter by name. Use --details to fetch full details (teams list) for each group by calling the detail API per entry. Available fields: ID, NAME, UPDATED_AT, TEAM_COUNT, TEAMS.

List IDP groups in the organization or connected to a team

gh team-kit idp list [team-slug] [--owner <[HOST/]OWNER>] [--query <name-filter>] [--field <field>] [--format <json|table>]

List all IDP groups available in the organization (SAML team sync), or list IDP groups connected to the specified team. Use --query to filter by name when listing all groups (not available when a team slug is provided). Available fields: ID, NAME, DESCRIPTION.

List teams connected to an external group

gh team-kit idp emu teams <group-name> [--owner <[HOST/]OWNER>] [--field <field>] [--format <json|table>]

List the teams connected to an external group, with detailed team info fetched from the organization (Enterprise Managed Users). Available fields: TEAM_ID, TEAM_NAME, SLUG, DESCRIPTION, PRIVACY, HTML_URL.

Remove the connection between an external group and a team

gh team-kit idp emu unset <team-slug> [--owner <[HOST/]OWNER>]

Remove the connection between an external group and a team in the organization (Enterprise Managed Users). Only the team slug is required.

Copilot Management

Show Copilot metrics for a team

gh team-kit copilot metrics <team-slug> [--owner <[HOST/]OWNER>] [--since <RFC3339>] [--until <RFC3339>]

Display GitHub Copilot usage metrics for the specified team. You can optionally specify the owner with --owner and limit the date range with --since and --until.

Code Review Management

Get code review settings

gh team-kit code-review get <team-slug> [--owner <[HOST/]OWNER>] [--format <json|table>]

Retrieve code review assignment settings for the specified team, including auto-assignment status, algorithm, member count, and notification preferences.

Set code review settings

gh team-kit code-review set <team-slug> [--owner <[HOST/]OWNER>] [--enabled|--disable-enabled] [--algorithm <ROUND_ROBIN|LOAD_BALANCE>] [--member-count <int>] [--notify-team|--disable-notify-team]

Update code review assignment settings for the specified team. You can enable/disable auto-assignment, set the assignment algorithm, configure the number of members to assign, and control team notifications.

Configuration Management

Export team information

gh team-kit export [--output <file>] [--owner <[HOST/]OWNER>] [--host <host>] [--no-export-repositories] [--no-export-group] [--no-export-org-roles] [--no-suspended] [--format <json|table>]

Retrieve and display team information from the specified organization. Exports team structure, members, maintainers, repositories, external group connections (EMU), custom organization role assignments, and code review settings to a file or stdout. Use --output to specify the output file (default: stdout). Use --no-export-repositories to skip repository permissions, --no-export-group to skip external group connections, --no-export-org-roles to skip custom org role assignments, and --no-suspended to exclude suspended users.

Import team information

gh team-kit import <input> [--dryrun] [--verify] [--owner <[HOST/]OWNER>] [--host <host>] [--usermap <file>] [--format <json|yaml>]

Read and apply team information to the specified organization from a file or stdin. Use --dryrun to preview changes without applying them. Specify - as input to read from stdin. Accepts YAML or JSON format. When --usermap is specified, source logins are resolved using the mapping file (as produced by user map). The src field supports regular expressions and dst may contain $N or ${name} capture-group references. If the input contains a group field for a team, the corresponding external group is connected automatically (EMU only; only applicable to leaf teams without parent/child teams). When the organization supports external groups and a team has no group specified, any existing external group connection is removed. If a team has an org_roles field, the listed custom organization roles are assigned to that team on import. See docs/migrate.md for migration examples.

Documentation

Overview

Copyright © 2025 srz_zumix