GitHub Teams Sync
Actions
Sync your GitHub organization teams from a declarative YAML configuration using the GitHub API.
- Syncs teams by name, description, and privacy
- Assigns maintainers and members
- Manages repository access and permissions
- Supports dry-run mode for safe testing
- Usable as a CLI or a reusable GitHub Action
- uses: actionsforge/actions-gh-teams-sync@v1
with:
config-path: .github/teams.yaml
dry-run: false
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}| Name | Description | Required | Default |
|---|---|---|---|
config-path |
Relative path to the YAML configuration file | No | .github/teams.yaml |
dry-run |
If true, prints planned changes without applying them | No | false |
# .github/teams.yaml
teams:
- name: platform-team # Required: Team name (will be converted to slug)
description: Platform engineers # Optional: Team description
privacy: closed # Optional: Team privacy ('closed' or 'secret', defaults to 'closed')
parent_team_id: 123 # Optional: ID of parent team for nested teams
create_default_maintainer: false # Optional: Whether to create default maintainer (defaults to false)
roles: # Optional: List of team members and their roles
- username: john # Required: GitHub username
role: maintainer # Required: Role ('member' or 'maintainer')
- username: alice
role: member
- username: bob
role: member
repositories: # Optional: List of repositories and their permissions
- name: platform-core # Required: Repository name
permission: admin # Required: Permission level
- name: platform-tools
permission: push
- name: data-team
description: Data engineering and analytics
privacy: secret # 'secret' teams are only visible to team members
roles:
- username: data-lead
role: maintainer
- username: analyst1
role: member
repositories:
- name: data-pipeline
permission: admin
- name: analytics-dashboard
permission: push| Parameter | Required | Description | Valid Values | Default |
|---|---|---|---|---|
name |
Yes | Team name | Any string | - |
description |
No | Team description | Any string | - |
privacy |
No | Team visibility | closed or secret |
closed |
parent_team_id |
No | ID of parent team | Number | - |
create_default_maintainer |
No | Create default maintainer | true or false |
false |
roles |
No | Team members and roles | Array of role objects | - |
repositories |
No | Repository access and permissions | Array of repository objects | - |
| Parameter | Required | Description | Valid Values |
|---|---|---|---|
username |
Yes | GitHub username | Valid GitHub username |
role |
Yes | Team role | member or maintainer |
| Parameter | Required | Description | Valid Values |
|---|---|---|---|
name |
Yes | Repository name | Valid repository name in the organization |
permission |
Yes | Access level | pull, triage, push, maintain, or admin |
# Dry run
GITHUB_TOKEN=ghp_... \
GITHUB_ORG=cloudbuildlab \
node dist/sync-teams.js --config .github/teams.yaml --dry-run
# Apply changes
GITHUB_TOKEN=ghp_... \
GITHUB_ORG=cloudbuildlab \
node dist/sync-teams.js --config .github/teams.yamlTo manage organization teams, use a token with the admin:org scope.
The default GITHUB_TOKEN only works in organization-owned repositories and must have the admin:org scope enabled via workflow permissions. https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token
This project is licensed under the MIT License. See the LICENSE file for details.
GitHub Teams Sync is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.
GitHub Teams Sync is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.