Skip to main content
The teams section grants teams access to repositories with specific permissions. Teams must exist in the organization, or Safe Settings will create them.

​
Basic Configuration

​
name
string
required
The name (slug) of the team. If the team doesn’t exist, Safe Settings will create it.
teams:
  - name: core
    permission: admin
​
permission
string
required
The permission to grant the team. Can be one of:
  • pull - Can pull, but not push to or administer this repository
  • push - Can pull and push, but not administer this repository
  • admin - Can pull, push and administer this repository
teams:
  - name: developers
    permission: push

​
Team Creation

​
privacy
string
The privacy level when creating a new team. Only used when the team doesn’t exist yet. Can be:
  • secret (default) - Only visible to organization owners and team members
  • closed - Visible to all members of the organization
Note: This setting is only honored when the team is created, not for existing teams.
teams:
  - name: globalteam
    permission: push
    visibility: closed

​
Include/Exclude Patterns

You can use include and exclude lists to control which repositories a team has access to. This is particularly useful for organization-level settings.
​
include
array
List of repository names where this team should have access. When specified, the team will only have access to these repositories.
teams:
  - name: platform-team
    permission: admin
    include:
      - api-service
      - web-app
      - database-layer
​
exclude
array
List of repository names where this team should not have access. The team will have access to all other repositories in the organization.
teams:
  - name: contractors
    permission: pull
    exclude:
      - internal-tools
      - security-repo

​
Security Manager Teams

Safe Settings automatically excludes teams with the “Security Manager” role from being managed. Security manager teams have special organization-wide permissions and should not be managed through repository-level settings.

​
Complete Examples

​
Basic Team Access

teams:
  - name: core
    permission: admin
  
  - name: developers
    permission: push
  
  - name: external-contributors
    permission: pull

​
Team with Visibility Setting

teams:
  - name: public-team
    permission: push
    visibility: closed  # Visible to all org members

​
Organization-Level with Include

# In org-level settings
teams:
  - name: frontend-team
    permission: push
    include:
      - web-app
      - mobile-app
      - design-system

​
Organization-Level with Exclude

# In org-level settings
teams:
  - name: all-developers
    permission: push
    exclude:
      - security-configs
      - infrastructure

​
How Include/Exclude Works

  • Include: When specified, creates an allowlist. The team will only have access to repositories in the include list.
  • Exclude: When specified, creates a denylist. The team will have access to all repositories except those in the exclude list.
  • Neither: When neither is specified, the team configuration applies to the current repository (repo-level settings) or all repositories (org-level settings).
  • Both: You should not specify both include and exclude for the same team.

​
Finding Team IDs

To find a team ID (needed for environment reviewers), use: 
gh api /orgs/<org>/teams/<team-slug> | jq .id

​
API Reference

For more details, see GitHub’s REST API documentation:

Build docs developers (and LLMs) love

Get started for freeTalk to us