Teams

Codebase Governor already creates maintainers and owner teams from your capability defaults. For the capability named git-flutter:

• The owner-cap-git-flutter team’s only member is the owner of the capability.
• The maintainers-cap-git-flutter team members are the maintainers of the capability.

If you need additional teams (e.g. for contributors), you can define them in the teams/ directory of the org-config repository in a team YAML configuration file. This page documents the location & format of these files.

There are 2 types of teams that CBG can manage:

1. Fixed teams
2. Elastic teams

Fixed Teams

Fixed teams have static membership, i.e. the members specified in the configuration file will always be a part of the team until they have been removed from the configuration or excluded using the exclude key.

Elastic Teams

Elastic teams have dynamic membership, i.e. the members will remain in the team as long as they have any activity in the configured capabilities in the last 6 months.

For new users who do not have any activity in the configured capabilities, but would like to be a member of an elastic team, they can request access by creating an issue in org-config using the issue template provided. The requested access will be valid for 6 months. After that, the user will only remain in the team if they meet the conditions detailed above.

Note: The current version of elastic teams allow any member of the all-flutter-global team to be a memberm of the team as long as they requested access or have any type of activity in the last 6 months in the configured capabilities.

Name

The team slug comes from your filename: teams/<your-team-slug>.yml. The team name is the same as the slug to avoid a common area of confusion between these fields when they’re different.

Example:

teams/
  contributors-cap-git-flutter.yml
  service-accounts.yml
  ...

These 2 YAML files in the team directory define the contributors-cap-git-flutter and service-accounts teams respectively.

Owners

The owners key specifies the owners of your team. The owners are responsible for approving any changes to the team’s config file through a PR in org-config. You can specify owners by GitHub username or use the members of another team.

• owners.users specifies individual GitHub usernames to act as owners.
• owners.teams specifies team(s) to act as owners.

Examples:

Typically, capability maintainers own a team:

owners:
  teams:
    - maintainers-cap-git-flutter

Or specific individuals own the team:

owners:
  users:
    - username-1
    - username-2

Members

The members key specifies the members of your team.

• members.users specifies individual GitHub usernames to be members.
• members.teams specifies members using other teams – anyone in the other team is also added to your team.

If you specify another team as a member, all changes in membership of that team propagate to your team. Cyclic dependencies aren’t permitted.

This key is currently not allowed in elastic teams. Use it only to configure fixed teams.

Examples:

This team has 2 members username-3 & username-4:

members:
  users:
    - username-3
    - username-4

This team includes username-3 & username-4, and also all the members of the maintainers-cap-git-flutter team.

members:
  users:
    - username-3
    - username-4
  teams:
    - maintainers-cap-git-flutter

Request Access

The requested-access key specifies the members who have requested access to an elastic team.

• requested-access.[].user specifies the GitHub username to add to the team
• requested-access.[].request-date specifies the date the access request was made

Example:

This team has 2 members who’ve requested access:

requested-access:
  - user: username-3
    date: 2024-05-17
  - user: username-4
    date: 2023-05-17

The access request for the user username-4 is older than 6 months ago and thus, the user is only expected to be a member of the team if they have any activity in the configured capabilities.

Activity

The only-if-active key specifies the the activity conditions for an elastic team. Currently, elastic teams only support capability and a fixed time window of 6 months.

• only-if-active.capabilities specifies the capabilities the user needs to have activity on in the last 6 months to remain in the team

Example:

only-if-active:
  capabilities:
    - capability-1
    - capability-2

Any member of the Flutter-Global GitHub org who has activity in capability-1 or in capability-2 will be a member of this example elastic team.

Exclusions

Use the exclude key to exclude any specific users or teams.

• exclude.users specifies individual GitHub usernames to exclude.
• exclude.teams specifies team(s) to exclude.

Example:

This example excludes any service accounts from the service-accounts team from being a member of the team:

owners:
  teams:
    - service-accounts

Examples

Fixed team

Let’s consider a contributor team for the codebases/git-flutter capability supporting a requested contribution access model.

In the file teams/contributors-cap-git-flutter.yml:

description: >
  Contributors who are granted write access to git-flutter repos.
  Members last reviewed by John Doe on 2024-05-12.

owners:
  teams:
    - maintainers-cap-git-flutter

members:
  users:
    - username-1  # required as part of his DevOps role in xxx
    - username-2  # required as part of her DevOps role in xyz
  teams:
    - maintainers-cap-git-flutter
    - a-devops-team # regularly contribute fixes for yyy

exclude:
  teams:
    - service-accounts # this is a human contributors team, no service accounts

Note how:

• The capability maintainers are the owners.
• You can directly specify members (username-1 & username-2), or assigned them by team (a-devops-team). When a user joins a-devops-team, they’ll join this team shortly afterwards too.
• You can exclude specific users or teams – in this case excluding all known service-accounts.
• You can use the description and comments to capture access review meta-data for audit.

Elastic team

Let’s consider a contributor team for the codebases/git-flutter capability supporting a requested contribution access model, but any members who haven’t requested access and are inactive in the capability for the last 6 months should be removed from the team.

In the file teams/contributors-cap-git-flutter.yml:

description: >
  Contributors who are granted write access to git-flutter repos.
  Members must have activity in the capability or requested access in the last 6 months.
  Members last reviewed by John Doe on 2024-05-12.

owners:
  teams:
    - maintainers-cap-git-flutter

requested-access:
  - user: username-3
    date: 2024-05-17
  
only-if-active:
  capabilities:
    - git-flutter

exclude:
  teams:
    - service-accounts # this is a human contributors team, no service accounts

Note how:

• The capability maintainers are the owners.
• You can directly specify which members have requested access and must have access to the team independently of whether they have activity in the last 6 months or not.
• You can directly specify which capabilities members who have not requested access in the last 6 months must have activity on to remain in the team.
• You can exclude specific users or teams – in this case excluding all known service-accounts.
• You can use the description and comments to capture access review meta-data for audit.