GitHub Team Management Documentation - mrCDray/team-managment GitHub Wiki

GitHub Team Management System Documentation

Overview

The GitHub Team Management System is an "Issue Ops" solution that enables teams to manage GitHub team structures, memberships, and repository permissions through GitHub issues. This documentation provides information about the system architecture, workflows, and user guides.

System Architecture

The Team Management System consists of the following components:

Components -

  1. Issue Template: A form-based template for team management operations
  2. GitHub Actions Workflows:
    • process-team-issue.yml - Processes issues with team management requests
    • sync-github-teams.yml - Syncs team configuration files with GitHub
  3. Python Scripts:
    • process_team_issue.py - Processes issue data and manages team configurations
    • sync_github_teams.py - Synchronizes team configurations with GitHub
  4. Configuration Files:
    • Team-specific YAML files (teams/<team-name>/teams.yml)
    • Default team configuration template (default_teams_config.yml)

Workflow

Team Structure and Hierarchy

The following diagram illustrates how teams are organized in the GitHub Team Management system:

graph TD
    ParentTeam["Parent Team<br>(a-team)"]
    
    Dev["Developer Team<br>a-team-developers<br><i>write access</i>"]
    Test["Tester Team<br>a-team-testers<br><i>triage access</i>"]
    Review["Reviewer Team<br>a-team-reviewers<br><i>write access</i>"]
    Release["Release Managers<br>a-team-release-managers<br><i>maintain access</i>"]
    Ops["Operations Team<br>a-team-operations<br><i>maintain access</i>"]
    Security["Security Team<br>a-team-security<br><i>admin access</i>"]
    Owners["Project Owners<br>a-team-project-owners<br><i>admin access</i>"]
    
    ParentTeam --> Dev
    ParentTeam --> Test
    ParentTeam --> Review
    ParentTeam --> Release
    ParentTeam --> Ops
    ParentTeam --> Security
    ParentTeam --> Owners
    
    User1["@username1"] --> ParentTeam
    User2["@username2"] --> ParentTeam
    
    User1 -.-> Dev
    User1 -.-> Test
    User2 -.-> Security
    User2 -.-> Owners

    style ParentTeam fill:#f9f,stroke:#333,stroke-width:2px
    style Dev fill:#bbf,stroke:#333
    style Test fill:#bbf,stroke:#333
    style Review fill:#bbf,stroke:#333
    style Release fill:#fdb,stroke:#333
    style Ops fill:#fdb,stroke:#333
    style Security fill:#fbb,stroke:#333
    style Owners fill:#fbb,stroke:#333
Loading

Issue Processing Flow

This diagram shows how team management issues are processed:

sequenceDiagram
    participant User
    participant GH as GitHub Issue
    participant WF as GitHub Actions Workflow
    participant Process as process_team_issue.py
    participant Config as YAML Configuration
    participant Sync as sync_github_teams.py
    participant API as GitHub API

    User->>GH: Create issue with team template
    GH->>WF: Trigger workflow on issue create/edit
    WF->>Process: Run with issue data
    
    Process->>Process: Parse issue body
    Process->>Process: Validate requested action
    
    alt Create team
        Process->>Config: Create new team config
    else Update team
        Process->>Config: Load existing config
        Process->>Config: Update team properties
    else Remove items
        Process->>Config: Load existing config
        Process->>Config: Remove items
    end
    
    Process->>Config: Save updated config
    Process->>GH: Comment with results
    Config-->>WF: Config changed, trigger sync workflow
    WF->>Sync: Run sync_github_teams.py
    Sync->>Config: Load team configs
    Sync->>API: Create/update teams
    Sync->>API: Manage team members
    Sync->>API: Set repository permissions
    API-->>GH: Teams updated in GitHub
Loading

Configuration Structure

The YAML configuration structure for teams:

graph TD
    Root["teams"]
    Parent["parent_team: team-name"]
    Desc["description: Team description"]
    Project["project: Project name"]
    Members["members: [user1, user2]"]
    Repos["repositories: [repo1, repo2]"]
    PermParent["repository_permissions: read"]
    ChildTeams["child_teams: []"]
    
    Root --> Parent
    Root --> Desc
    Root --> Project
    Root --> Members
    Root --> Repos
    Root --> PermParent
    Root --> ChildTeams
    
    Child1["name: team-name-developers"]
    Child1Desc["description: Developers"]
    Child1Mem["members: [user1]"] 
    Child1Repos["repositories: [repo1, repo2]"]
    Child1Perm["repository_permissions: write"]
    
    ChildTeams --> Child1
    Child1 --> Child1Desc
    Child1 --> Child1Mem
    Child1 --> Child1Repos
    Child1 --> Child1Perm
    
    Child2["name: team-name-testers"]
    Child2Desc["description: Testers"]
    Child2Mem["members: [user2]"]
    Child2Repos["repositories: [repo1, repo2]"]
    Child2Perm["repository_permissions: triage"]
    
    ChildTeams --> Child2
    Child2 --> Child2Desc
    Child2 --> Child2Mem
    Child2 --> Child2Repos
    Child2 --> Child2Perm
Loading

User Journey for Team Management

journey
    title Team Management Journey
    section Create Team
        Fill issue template: 5: User
        Select 'create' action: 5: User
        Enter team name & project: 4: User
        Add team description: 4: User
        Add team members: 3: User
        Add repositories: 3: User
        Submit issue: 5: User
        Review result comment: 4: User
    section Update Team
        Fill issue template: 5: User
        Select 'update' action: 5: User
        Enter existing team name: 5: User
        Add/modify members: 3: User
        Add repositories: 3: User
        Submit issue: 4: User
        Review result comment: 4: User
    section Remove Members/Repos
        Fill issue template: 5: User
        Select 'remove' action: 5: User
        Enter existing team name: 5: User
        List members to remove: 3: User
        List repos to remove: 3: User
        Submit issue: 4: User
        Review result comment: 4: User
Loading

Team Structure

Teams are organized hierarchically:

  • Parent Team: The main team (e.g., a-team)
  • Child Teams: Specialized sub-teams with specific permissions:
    • [team-name]-developers: Write access to repositories
    • [team-name]-testers: Triage access to repositories
    • [team-name]-reviewers: Write access to repositories
    • [team-name]-release-managers: Maintain access to repositories
    • [team-name]-operations: Maintain access to repositories
    • [team-name]-security: Admin access to repositories
    • [team-name]-project-owners: Admin access to repositories

User Guide: Managing Teams Through Issues

Creating a New Team

  1. Create a new issue using the "Team Management" template
  2. Set the Action to create
  3. Enter the Team Name (without spaces, using kebab-case)
  4. Specify the Project Name
  5. Provide a meaningful Team Description
  6. Add Members (optional) using the format: 
    - @username (developers, testers)
- @another-user (all)
  7. Add Repositories (optional): 
    - repository-name
- another-repo
  8. Define Child Teams (optional) using the format: 
    - child-team:Description:permission
    For example: 
    - developers:Development team:write

Updating an Existing Team

  1. Create a new issue using the "Team Management" template
  2. Set the Action to update
  3. Enter the Team Name (must be an existing team)
  4. Add new members or repositories using the same format as creation
  5. Add or update child teams as needed

Removing Items from a Team

  1. Create a new issue using the "Team Management" template
  2. Set the Action to remove
  3. Enter the Team Name (must be an existing team)
  4. List members or repositories to remove using the same format
  5. List child teams to remove

Step-by-step Visual Guide

graph TD
    A[Start] --> B{Choose Action}
    
    B -->|Create| C1[Fill required fields]
    C1 --> D1[Enter team name]
    D1 --> E1[Enter project name]
    E1 --> F1[Enter team description]
    F1 --> G1[Add members & repos]
    G1 --> H[Submit issue]
    
    B -->|Update| C2[Fill required fields]
    C2 --> D2[Enter existing team name]
    D2 --> G2[Add/modify members & repos]
    G2 --> H
    
    B -->|Remove| C3[Fill required fields]
    C3 --> D3[Enter existing team name]
    D3 --> G3[List members/repos to remove]
    G3 --> H
    
    H --> I[GitHub Actions runs]
    I --> J[Python script processes issue]
    J --> K[Team config updated/created]
    K --> L[GitHub teams synced]
    L --> M[Issue commented with results]
    M --> N[End]
Loading

Permissions Reference

GitHub repository permissions map to the following access levels:

Configuration Value GitHub API Value Access Level
read pull Read-only access
write push Read/write access
triage triage Read and triage issues/PRs
maintain maintain Read/write plus some admin
admin admin Full administrator access

Member Assignment Format

You can assign members to specific child teams using the following format:

- @username (team1, team2, ...)

Special keywords:

  • all - Adds the member to all child teams
  • developers - Adds to the developers team
  • reviewers - Adds to the code reviewers team
  • testers - Adds to the testers team
  • operations - Adds to the operations team
  • security - Adds to the security team
  • release-managers - Adds to the release managers team
  • project-owners - Adds to the project owners team

Script Execution Flow

flowchart TD
    A[process_team_issue.py] --> B[Parse issue body]
    B --> C[Validate input data]
    C --> D{What action?}
    
    D -->|create| E[Create team config]
    D -->|update| F[Update team config]
    D -->|remove| G[Remove items from config]
    
    E --> H[Save team config]
    F --> H
    G --> H
    
    H --> I[Comment on issue]
    I --> J[Trigger sync workflow]
    
    J --> K[sync_github_teams.py]
    K --> L[Load team configs]
    L --> M[Create/update GitHub teams]
    M --> N[Sync team members]
    N --> O[Set repo permissions]
Loading

Troubleshooting Guide

Common Issues and Solutions

Issue: User Not Found

Problem: When adding a member, you receive a message that the user doesn't exist in the organization. Solution:

  • Verify the username is spelled correctly
  • Ensure the user is a member of the organization
  • Check if the user needs to be invited to the organization first

Issue: Repository Not Found

Problem: When adding a repository, you receive a message that the repository doesn't exist. Solution:

  • Check the repository name spelling
  • Verify the repository exists in the organization
  • Ensure the repository name doesn't include the organization prefix

Issue: Invalid Permission

Problem: An invalid permission is specified for a child team. Solution:

  • Use only these valid permissions: read, write, triage, maintain, admin
  • When in doubt, use "read" as the default permission

Issue: Workflow Failed

Problem: The GitHub Actions workflow failed to process the issue. Solution:

  • Check the workflow run logs for specific errors
  • Verify all required fields are filled in correctly
  • Ensure the issue has the "team-management" label

Best Practices

  1. Use descriptive team names that clearly indicate their purpose
  2. Keep team hierarchies simple to avoid confusion
  3. Document team purposes in the description field
  4. Review team memberships regularly and remove inactive members
  5. Use the least privilege principle when assigning permissions
  6. Test with non-critical repositories before adding important ones
  7. Create separate issues for different teams rather than combining multiple teams in one issue
  8. Check issue comments for validation errors and warnings

Advanced Usage

Managing Multiple Teams

If you need to manage multiple teams, create separate issues for each team. This helps keep the change history clear and makes it easier to track issues.

Team Synchronization

The system automatically synchronizes team configurations to GitHub after changes are committed. If you need to trigger synchronization manually, you can:

  1. Go to the "Actions" tab in the repository
  2. Select the "Sync GitHub Teams" workflow
  3. Click "Run workflow"
  4. Optionally specify a team name to sync only that team

Viewing Team Configurations

Team configurations are stored in YAML files at:

teams/<team-name>/teams.yml

You can view these files to see the current team structure, membership, and permissions.

This documentation should help users understand and effectively use the GitHub Team Management system. If you encounter any issues not covered here, please create an issue in the repository for assistance.

⚠️ **GitHub.com Fallback** ⚠️