Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rmacklin/team-sync
A GitHub action to synchronize GitHub Teams with the contents of a teams document
https://github.com/rmacklin/team-sync
github-actions github-team team-sync
Last synced: 2 months ago
JSON representation
A GitHub action to synchronize GitHub Teams with the contents of a teams document
- Host: GitHub
- URL: https://github.com/rmacklin/team-sync
- Owner: rmacklin
- License: mit
- Created: 2020-04-01T06:25:05.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-07-19T04:00:22.000Z (over 1 year ago)
- Last Synced: 2024-09-16T15:46:28.437Z (3 months ago)
- Topics: github-actions, github-team, team-sync
- Language: TypeScript
- Homepage:
- Size: 724 KB
- Stars: 10
- Watchers: 2
- Forks: 7
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# team-sync
This is a GitHub action to synchronize GitHub Teams with the contents of a teams
document in an organization repository.## Usage
1. Choose or create a repository in your organization for this action. If your
organization is already using a `.github` repository to manage GitHub files
like Issue and PR templates across the organization, that's a good choice.2. Create a `.github/teams.yml` file in that repository with the following
format:
```yml
designers:
description: The amazing design team
slack: "#design-team"
members:
- name: Alice Smith
github: alicesmith
- name: Bob Jones
github: bjonesdev
fighters:
members:
- name: Dave Grohl
github: dgrohl
- name: Taylor Hawkins
github: taylorhawk1
```
For the team sync, what's important is that the outer object maps each team
name to an object with a `members` array of objects containing a `github`
key. Any other fields can be included in the `members` objects (e.g. `name`,
`email`, etc.) but `github` is the required one that declares which GitHub
users should be part of each team.If you provide a `description` field alongside the `members` array, this
description will be synced to the GitHub Team's description. Any other fields
can be included alongside these two (e.g. Slack channel, Trello board URL,
etc.), though they will be ignored by the action.3. As an organization administrator, generate a [Personal Access Token] with the
`admin:org` scope. Enable SSO for the token if necessary for your
organization. (The `admin:org` scope is necessary to manage GitHub Teams.) If
your repository is private, you also need to include the `repo` scope.[Personal Access Token]: https://github.com/settings/tokens
4. In the repository settings, create a new Secret called
`ORG_ADMIN_ACCESS_TOKEN` to store the token. (The name of the secret is not
important, as long you use that name to configure the `repo-token` secret
below.)5. Create a `.github/workflows/team_sync.yml` file like this:
```yml
name: 'Team Sync'
on:
push:
branches:
- main
paths:
- '.github/teams.yml'jobs:
synchronize-teams:
runs-on: ubuntu-latest
steps:
- uses: rmacklin/team-sync@v0
with:
repo-token: "${{ secrets.ORG_ADMIN_ACCESS_TOKEN }}"
```Now your team can create pull requests that update the `teams.yml` file and when
they are merged to `main`, the GitHub Teams in your organization will be
created/updated according to those changes!## Additional Configuration
### `prefix-teams-with`
For large organizations, it may be more appropriate/practical to manage teams
within a subdivision of the larger organization. However, team names still have
to be unique across the whole GitHub organization. To support this, you can
specify the `prefix-teams-with` attribute in the action configuration:`.github/workflows/team_sync.yml`:
```yml
name: 'Team Sync'
on:
push:
branches:
- main
paths:
- '.github/teams.yml'jobs:
synchronize-teams:
runs-on: ubuntu-latest
steps:
- uses: rmacklin/team-sync@v0
with:
repo-token: "${{ secrets.ORG_ADMIN_ACCESS_TOKEN }}"
prefix-teams-with: 'foo'
````.github/teams.yml`:
```yml
designers:
description: The amazing design team
members:
- name: Alice Smith
github: alicesmith
- name: Bob Jones
github: bjonesdev
fighters:
members:
- name: Dave Grohl
github: dgrohl
- name: Taylor Hawkins
github: taylorhawk1
```
This configuration would create the teams `foo designers` and `foo fighters`
(rather than `designers` and `fighters`).### `team-data-path`
By default, the action looks for the team data in the `.github/teams.yml` file
in your repository. You can specify the `team-data-path` option to change this.
(Note that you'll also want to change the `paths` configuration specified in the
workflow definition.) For example, if you want to keep `teams.yml` in the root
of your repository, you could use:
```yml
name: 'Team Sync'
on:
push:
branches:
- main
paths:
- 'teams.yml'jobs:
synchronize-teams:
runs-on: ubuntu-latest
steps:
- uses: rmacklin/team-sync@v0
with:
repo-token: "${{ secrets.ORG_ADMIN_ACCESS_TOKEN }}"
team-data-path: 'teams.yml'
```### The `team_sync_ignored` property
You can add `"team_sync_ignored": true` to a team's properties to prevent that
team from being synchronized with a corresponding GitHub Team.## Fine print
Note that if you rename a team (in a way that updates the team's computed slug),
this action will create a new team with the new name, rather than updating the
old team. This action will *not* delete any teams since doing so is very
destructive and difficult to reverse. (Even if you are using this action to
manage GitHub teams, it still permits the existence of other teams in the
organization that are managed elsewhere.) So, if you want to rename a team in a
way that changes its slug, you should rename the GitHub Team before you update
your teams document with the new name. Otherwise you'll need to manually delete
the old GitHub Team after this action creates a new GitHub Team using the new
name.