GitHub Bulk Collaborator Management Script A Windows batch script that allows you to add collaborators to multiple GitHub repositories

add_github_collaborator.bat

@echo off
setlocal enabledelayedexpansion

REM ===================================================================
REM GitHub Bulk Collaborator Management Script
REM ===================================================================
REM This script adds a collaborator to multiple GitHub repositories
REM in bulk using the GitHub CLI (gh).
REM
REM Prerequisites:
REM - GitHub CLI must be installed (winget install --id GitHub.cli)
REM - You must be authenticated with GitHub (gh auth login)
REM - You must have admin access to the repositories you want to modify
REM
REM Usage:
REM 1. Edit the CONFIGURATION section below
REM 2. Run this script from command prompt or PowerShell
REM
REM Author: Generated for public use
REM License: MIT
REM ===================================================================

echo ====================================
echo GitHub Bulk Collaborator Management
echo ====================================
echo.

REM ===================================================================
REM CONFIGURATION SECTION - EDIT THESE VALUES
REM ===================================================================

REM Set the GitHub username of the person you want to add as collaborator
REM Replace "username" with the actual GitHub username (not email)
set COLLABORATOR_USERNAME=username

REM Set the permission level for the collaborator
REM Valid options: read, write, admin, maintain, triage
REM - read: Can read and clone repositories
REM - write: Can read, clone, and push to repositories  
REM - admin: Full access including settings and collaborator management
REM - maintain: Can manage some repository settings but not sensitive ones
REM - triage: Can manage issues and pull requests but not push code
set PERMISSION=write

REM List of repository names to add the collaborator to
REM Add or remove repository names as needed, separated by spaces
REM Example: set REPOS=repo1 repo2 repo3 my-awesome-project
set REPOS=repo1 repo2 repo3

REM ===================================================================
REM VALIDATION SECTION - DO NOT EDIT BELOW THIS LINE
REM ===================================================================

REM Validate that configuration has been set
if "!COLLABORATOR_USERNAME!"=="username" (
    echo ERROR: Please edit the COLLABORATOR_USERNAME in this script first
    echo Open this file in a text editor and set the GitHub username you want to add
    pause
    exit /b 1
)

if "!REPOS!"=="repo1 repo2 repo3" (
    echo ERROR: Please edit the REPOS list in this script first  
    echo Open this file in a text editor and set your actual repository names
    pause
    exit /b 1
)

echo Configuration:
echo - Collaborator: !COLLABORATOR_USERNAME!
echo - Permission: !PERMISSION!
echo - Repositories: !REPOS!
echo.

REM ===================================================================
REM GITHUB CLI VERIFICATION
REM ===================================================================

echo Checking GitHub CLI installation...

REM Check if GitHub CLI is available in PATH
gh --version >nul 2>&1
if errorlevel 1 (
    REM Try with full path if not in PATH
    "C:\Program Files\GitHub CLI\gh.exe" --version >nul 2>&1
    if errorlevel 1 (
        echo ERROR: GitHub CLI is not installed
        echo.
        echo Please install GitHub CLI using one of these methods:
        echo 1. winget install --id GitHub.cli
        echo 2. Download from: https://github.com/cli/cli/releases
        echo 3. Use package manager: choco install gh
        echo.
        echo After installation, restart your terminal and try again.
        pause
        exit /b 1
    ) else (
        REM Add to PATH for this session
        set "PATH=%PATH%;C:\Program Files\GitHub CLI"
        echo ✅ GitHub CLI found and added to PATH for this session
    )
) else (
    echo ✅ GitHub CLI is installed and available
)

REM ===================================================================
REM AUTHENTICATION VERIFICATION  
REM ===================================================================

echo Checking GitHub authentication...

REM Check if user is authenticated with GitHub
gh auth status >nul 2>&1
if errorlevel 1 (
    echo ❌ You are not authenticated with GitHub.
    echo.
    echo Please authenticate using ONE of these methods:
    echo 1. Run: gh auth login --web   ^(opens browser for authentication^)
    echo 2. Run: gh auth login --with-token   ^(paste your personal access token^)
    echo.
    echo To create a personal access token:
    echo 1. Go to: https://github.com/settings/tokens
    echo 2. Click "Generate new token" ^(classic^)
    echo 3. Select scopes: repo, admin:org, user
    echo 4. Copy the token and use with: gh auth login --with-token
    echo.
    echo After authentication, run this script again.
    pause
    exit /b 1
) else (
    echo ✅ GitHub authentication verified
)

REM ===================================================================
REM GET CURRENT USER INFORMATION
REM ===================================================================

echo Getting current user information...

REM Get current authenticated user to determine repository owner
for /f "tokens=*" %%i in ('gh api user -q .login 2^>nul') do set CURRENT_USER=%%i

if "!CURRENT_USER!"=="" (
    echo ERROR: Could not determine current GitHub user
    echo This might indicate an authentication problem
    pause
    exit /b 1
)

echo ✅ Current GitHub user: !CURRENT_USER!
echo.

REM ===================================================================
REM COLLABORATOR VALIDATION
REM ===================================================================

echo Validating collaborator username...

REM Check if the collaborator username exists on GitHub
gh api users/!COLLABORATOR_USERNAME! >nul 2>&1
if errorlevel 1 (
    echo ❌ ERROR: GitHub user '!COLLABORATOR_USERNAME!' does not exist
    echo Please check the username spelling and try again
    pause
    exit /b 1
) else (
    echo ✅ GitHub user '!COLLABORATOR_USERNAME!' exists
)

echo.
echo Ready to add !COLLABORATOR_USERNAME! as collaborator with '!PERMISSION!' permissions
echo to repositories owned by !CURRENT_USER!
echo.
echo Press any key to continue or Ctrl+C to cancel...
pause >nul
echo.

REM ===================================================================
REM BULK COLLABORATOR ADDITION PROCESS
REM ===================================================================

REM Initialize counters for summary
set SUCCESS_COUNT=0
set FAILURE_COUNT=0
set TOTAL_COUNT=0

echo Processing repositories...
echo.

REM Create temporary file for capturing error details
set TEMP_ERROR_FILE=%TEMP%\gh_collaborator_error_%RANDOM%.txt

REM Loop through each repository in the list
for %%r in (%REPOS%) do (
    set /a TOTAL_COUNT+=1
    echo [!TOTAL_COUNT!] Processing repository: %%r
    
    REM First verify that the repository exists and is accessible
    gh repo view !CURRENT_USER!/%%r >nul 2>&1
    if errorlevel 1 (
        echo    ❌ FAILED: Repository '%%r' does not exist or is not accessible
        echo       Make sure the repository name is correct and you have access
        set /a FAILURE_COUNT+=1
    ) else (
        REM Repository exists, attempt to add collaborator
        REM Use GitHub API to add collaborator with specified permission
        gh api repos/!CURRENT_USER!/%%r/collaborators/!COLLABORATOR_USERNAME! -X PUT -f permission=!PERMISSION! >!TEMP_ERROR_FILE! 2>&1
        
        if errorlevel 1 (
            echo    ❌ FAILED: Could not add collaborator to '%%r'
            echo       Possible reasons:
            echo       - You don't have admin access to this repository
            echo       - Repository settings don't allow external collaborators  
            echo       - Network error or API rate limit
            echo       Error details:
            type !TEMP_ERROR_FILE! 2>nul | findstr /v "^$"
            set /a FAILURE_COUNT+=1
        ) else (
            echo    ✅ SUCCESS: Added !COLLABORATOR_USERNAME! to '%%r'
            set /a SUCCESS_COUNT+=1
        )
    )
    echo.
)

REM Clean up temporary error file
if exist !TEMP_ERROR_FILE! del !TEMP_ERROR_FILE! >nul 2>&1

REM ===================================================================
REM RESULTS SUMMARY
REM ===================================================================

echo ====================================
echo OPERATION SUMMARY
echo ====================================
echo Total repositories processed: !TOTAL_COUNT!
echo Successful additions: !SUCCESS_COUNT!
echo Failed additions: !FAILURE_COUNT!
echo.

REM Provide detailed information about failures if any occurred
if !FAILURE_COUNT! gtr 0 (
    echo ⚠️  TROUBLESHOOTING FAILURES:
    echo.
    echo Common reasons for failures:
    echo 1. Repository doesn't exist under your account (!CURRENT_USER!)
    echo 2. You don't have admin access to the repository
    echo 3. The GitHub username '!COLLABORATOR_USERNAME!' is incorrect
    echo 4. Repository settings don't allow external collaborators
    echo 5. Organization policies restrict collaborator additions
    echo 6. Network errors or GitHub API rate limiting
    echo.
    echo Manual alternatives for failed repositories:
    echo 1. Use GitHub web interface: https://github.com/!CURRENT_USER!/REPO_NAME/settings/access
    echo 2. Contact repository owners if you don't have admin access
    echo 3. Check organization settings if repositories are under an organization
)

REM Provide success information
if !SUCCESS_COUNT! gtr 0 (
    echo.
    echo ✅ SUCCESS DETAILS:
    echo.
    echo !COLLABORATOR_USERNAME! will receive email invitations for successful additions
    echo and must accept them to gain access to the repositories.
    echo.
    echo Permission level granted: !PERMISSION!
    if "!PERMISSION!"=="read" (
        echo - Can view and clone repositories
        echo - Cannot push changes or modify settings
    )
    if "!PERMISSION!"=="write" (
        echo - Can view, clone, and push to repositories
        echo - Cannot modify repository settings
    )
    if "!PERMISSION!"=="admin" (
        echo - Full access including repository settings
        echo - Can manage collaborators and repository configuration
    )
    if "!PERMISSION!"=="maintain" (
        echo - Can manage repository without sensitive settings access
        echo - Can manage issues, pull requests, and some settings
    )
    if "!PERMISSION!"=="triage" (
        echo - Can manage issues and pull requests
        echo - Cannot push code or modify repository settings
    )
)

echo.
echo Script completed. Press any key to exit...
pause >nul 

add_github_collaborator.md

GitHub Bulk Collaborator Management Script

A Windows batch script that allows you to add collaborators to multiple GitHub repositories in bulk using the GitHub CLI. Perfect for repository maintainers, team leads, and organizations who need to efficiently grant access to new team members across multiple projects.

🚀 Features

• Bulk Operations: Add one collaborator to multiple repositories with a single command
• Flexible Permissions: Support for all GitHub permission levels (read, write, admin, maintain, triage)
• Smart Validation: Built-in checks for GitHub CLI installation, authentication, and user existence
• Detailed Reporting: Progress indicators and comprehensive success/failure summaries
• Error Handling: Robust error detection with specific troubleshooting guidance
• Organization Support: Works with both personal and organization repositories
• Safe Operation: Confirmation prompts and validation before making changes

📋 Prerequisites

Before using this script, ensure you have:

1. GitHub CLI installed: Download from GitHub CLI or install via:

   winget install --id GitHub.cli

2. GitHub Authentication: Authenticate with GitHub CLI using one of these methods:

   Method 1: Web Browser Authentication (Recommended)

   gh auth login --web

   This will open your browser and guide you through GitHub's OAuth flow.

   Method 2: Personal Access Token

   gh auth login --with-token

   Then paste your personal access token when prompted. To create a token:

   • Go to GitHub Settings > Personal Access Tokens
   • Click "Generate new token (classic)"
   • Select scopes: repo, admin:org, user
   • Copy the generated token and paste it in the terminal

3. Admin Access: You must have admin permissions on the repositories you want to modify

4. Windows Environment: This is a Windows batch script (.bat file)

🔧 Configuration

Edit these three variables at the top of the script:

1. Collaborator Username

set COLLABORATOR_USERNAME=username

Replace username with the actual GitHub username (not email address) of the person you want to add.

2. Permission Level

set PERMISSION=write

Choose from these permission levels:

• read: Can view and clone repositories
• write: Can view, clone, and push to repositories
• admin: Full access including settings and collaborator management
• maintain: Can manage some repository settings but not sensitive ones
• triage: Can manage issues and pull requests but not push code

3. Repository List

set REPOS=repo1 repo2 repo3

Replace with your actual repository names, separated by spaces. Example:

set REPOS=my-website my-api-project documentation-site

🔐 Quick Setup Guide

First-Time GitHub CLI Setup

If you've never used GitHub CLI before, follow these steps:

1. Install GitHub CLI (if not already installed):

   winget install --id GitHub.cli

2. Open a new terminal window (Command Prompt or PowerShell)

3. Authenticate with GitHub:

   gh auth login --web

   • This will display a code and open your browser
   • Authorize the GitHub CLI application
   • Return to terminal when prompted

4. Verify authentication:

   gh auth status

   You should see your username and "Logged in to github.com"

💻 Usage

1. Download the script: Save the batch file to your computer
2. Configure: Edit the three configuration variables as described above
3. Run: Execute the script from Command Prompt or PowerShell
4. Follow prompts: The script will guide you through the process

Example Workflow

# Navigate to script location
cd C:\path\to\script

# Run the script
add_github_collaborator.bat

📊 Output Example

The script provides detailed output including:

====================================
GitHub Bulk Collaborator Management
====================================

Configuration:
- Collaborator: johndoe
- Permission: write
- Repositories: website api docs

✅ GitHub CLI is installed and available
✅ GitHub authentication verified
✅ Current GitHub user: myusername
✅ GitHub user 'johndoe' exists

Ready to add johndoe as collaborator with 'write' permissions
to repositories owned by myusername

[1] Processing repository: website
    ✅ SUCCESS: Added johndoe to 'website'

[2] Processing repository: api
    ✅ SUCCESS: Added johndoe to 'api'

[3] Processing repository: docs
    ❌ FAILED: Repository 'docs' does not exist or is not accessible

====================================
OPERATION SUMMARY
====================================
Total repositories processed: 3
Successful additions: 2
Failed additions: 1

🔍 Troubleshooting

Common Issues and Solutions

Authentication Problems

• Issue: "You are not authenticated with GitHub"

• Solutions:

  Option 1: Web Authentication (Easiest)

  gh auth login --web

  • This opens your browser automatically
  • Click "Authorize github" when prompted
  • Follow the on-screen instructions
  • Return to terminal once complete

  Option 2: Device Code Authentication

  gh auth login

  • Select "GitHub.com"
  • Choose "HTTPS" for Git operations
  • Choose "Login with a web browser"
  • Copy the provided code and open the URL
  • Paste the code in your browser

  Option 3: Personal Access Token

  gh auth login --with-token

  • Create a token at GitHub Settings
  • Required scopes: repo, admin:org, user
  • Paste the token when prompted in terminal

  Verify Authentication:

  gh auth status

  This should show your logged-in status and available scopes.

Repository Access Issues

• Issue: "Repository does not exist or is not accessible"
• Solutions:
  • Verify repository name spelling
  • Ensure you have admin access to the repository
  • Check if repository is under your personal account vs an organization

Permission Errors

• Issue: "Could not add collaborator"
• Solutions:
  • Verify you have admin rights to the repository
  • Check organization policies that might restrict collaborator additions
  • Ensure the repository allows external collaborators

GitHub CLI Issues

• Issue: "GitHub CLI is not installed"
• Solutions:
  • Install via winget install --id GitHub.cli
  • Download from GitHub CLI releases
  • Add GitHub CLI to your system PATH

🔒 Security Considerations

• The script only adds collaborators; it doesn't remove or modify existing ones
• All operations are logged with detailed output for audit purposes
• The script validates usernames before attempting to add them
• Requires explicit confirmation before making changes
• Uses GitHub's official API through the GitHub CLI

📝 Manual Alternative

For repositories that fail automation, you can manually add collaborators via:

1. Navigate to https://github.com/USERNAME/REPOSITORY/settings/access
2. Click "Add people"
3. Enter the collaborator's username
4. Select the appropriate permission level
5. Click "Add USERNAME to this repository"

🤝 Contributing

Feel free to suggest improvements or report issues. This script is designed to be simple, safe, and effective for bulk collaborator management.

📄 License

MIT License - Feel free to use, modify, and distribute as needed.

---

Note: This script is designed for Windows environments. For macOS/Linux users, consider adapting the logic to a shell script format.