Skip to main content
The collaborators section grants individual users access to repositories with specific permissions. This is useful for giving access to external contributors or individuals who are not part of a team.

​
Basic Configuration

​
username
string
required
The GitHub username of the collaborator. Usernames are automatically converted to lowercase to avoid comparison issues.
collaborators:
  - username: octocat
    permission: push
​
permission
string
required
The permission to grant the collaborator. 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
collaborators:
  - username: external-contributor
    permission: pull

​
Include/Exclude Patterns

You can use include and exclude lists to control which repositories a collaborator has access to. This is particularly useful for organization-level settings.
​
include
array
List of repository names where this collaborator should have access. When specified, the collaborator will only have access to these repositories.
collaborators:
  - username: contractor-alice
    permission: push
    include:
      - project-alpha
      - project-beta
​
exclude
array
List of repository names where this collaborator should not have access. The collaborator will have access to all other repositories in the organization.
collaborators:
  - username: temporary-access
    permission: pull
    exclude:
      - sensitive-repo
      - internal-tools

​
Pending Invitations

Safe Settings handles both active collaborators and pending invitations:
  • Active collaborators: Users who have accepted their invitation
  • Pending invitations: Users who have been invited but haven’t accepted yet
If a collaborator’s permission changes while their invitation is pending, Safe Settings will update the invitation with the new permission level.

​
Complete Examples

​
Basic Collaborator Access

collaborators:
  - username: octocat
    permission: push
  
  - username: external-reviewer
    permission: pull
  
  - username: repo-admin
    permission: admin

​
Organization-Level with Include

# In org-level settings
collaborators:
  - username: contractor-bob
    permission: push
    include:
      - frontend-project
      - design-assets

​
Organization-Level with Exclude

# In org-level settings
collaborators:
  - username: external-auditor
    permission: pull
    exclude:
      - private-configs
      - security-repo

​
Mixed Patterns

collaborators:
  # Access to all repos (repo-level settings)
  - username: trusted-contributor
    permission: push
  
  # Limited to specific repos (org-level settings)
  - username: specialist
    permission: push
    include:
      - data-pipeline
  
  # Access to all except specific repos (org-level settings)
  - username: temporary-help
    permission: pull
    exclude:
      - production-config

​
How Include/Exclude Works

  • Include: When specified, creates an allowlist. The collaborator will only have access to repositories in the include list.
  • Exclude: When specified, creates a denylist. The collaborator will have access to all repositories except those in the exclude list.
  • Neither: When neither is specified, the collaborator 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 collaborator.

​
Collaborators vs Teams

Use collaborators when:
  • Granting access to external contributors
  • Giving access to individuals not in your organization
  • Providing temporary or limited access
Use teams when:
  • Managing access for groups of organization members
  • Applying consistent permissions across multiple people
  • Organizing people by project or responsibility

​
Finding User IDs

To find a user ID (needed for environment reviewers), use: 
gh api /users/<username> | 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