bytelyst-devops-tools/docs/remove_user_interactive.md

Interactive User Removal Tool

Overview

remove_user_interactive.sh is a comprehensive command-line tool designed to remove users from GitHub repositories with advanced pattern matching and interactive confirmation features. The tool supports both individual user repositories and organization-wide operations.

Features

🎯 Core Functionality

• Interactive User Input: Guides users through token, user, and pattern collection
• Multi-Level Repository Discovery: Handles both root account and organization repositories
• Wildcard Pattern Matching: Supports complex repository patterns
• Batch Operations: Process multiple repositories efficiently
• Rich Visual Feedback: Color-coded logging with progress indicators

🔐 Security Features

• Token Validation: Verifies GitHub API access before operations
• Interactive Confirmations: Prevents accidental bulk operations
• Permission Checks: Validates repository access permissions
• Error Handling: Comprehensive error reporting and recovery

🎨 User Experience

• Progress Tracking: Real-time progress indicators
• Flexible Confirmation System: Multiple response options
• Summary Reports: Detailed operation statistics
• Color-Coded Output: Enhanced readability with emojis

Usage

Basic Execution

./remove_user_interactive.sh

Interactive Flow

1. Dependency Check: Validates required tools (curl, jq)
2. Authentication: Collects and validates GitHub token
3. Root User Input: Specifies the root account/organization
4. Target User: Defines the user to remove
5. Pattern Matching: Sets repository selection criteria
6. Repository Discovery: Finds all matching repositories
7. Confirmation: Reviews and confirms the operation
8. Batch Processing: Removes user from selected repositories
9. Summary Report: Displays operation results

Pattern Matching

The tool supports sophisticated wildcard patterns for repository selection:

Pattern Examples

• *-go-api* - Matches any repository containing "-go-api"
• frontend-* - Matches repositories starting with "frontend-"
• *-service - Matches repositories ending with "-service"
• web-*-app - Matches repositories with "web-" prefix and "-app" suffix
• exact-repo-name - Matches specific repository name

Pattern Behavior

• Patterns are case-sensitive
• Wildcards (*) match any sequence of characters
• Patterns apply to repository names, not full paths
• Multiple patterns can be combined using shell globbing

Interactive Confirmation System

During the removal process, users have multiple response options:

Confirmation Options

• [y]es - Remove user from current repository
• [n]o - Skip current repository
• [a]ll yes - Remove user from all remaining repositories
• [s]kip all - Skip all remaining repositories
• [q]uit - Cancel entire operation

Confirmation Modes

• ask - Default mode, prompts for each repository
• yes_all - Automatically confirm all operations
• no_all - Automatically skip all operations

Repository Discovery

The tool performs comprehensive repository discovery:

Discovery Process

1. Root User Repositories: Fetches all repositories owned by the root user
2. Organization Discovery: Identifies organizations the root user belongs to
3. Organization Repositories: Fetches repositories from each organization
4. Pattern Filtering: Applies wildcard patterns to repository names
5. Deduplication: Removes duplicate repositories from the final list

API Endpoints Used

• GET /users/{user}/repos - User repositories
• GET /users/{user}/orgs - User organizations
• GET /orgs/{org}/repos - Organization repositories
• DELETE /repos/{owner}/{repo}/collaborators/{username} - Remove collaborator

Error Handling

The tool includes comprehensive error handling:

HTTP Status Codes

• 204 - Successful removal
• 404 - User not found or not a collaborator
• 403 - Insufficient permissions
• 401 - Invalid authentication

Error Recovery

• Network Failures: Retry mechanisms for API calls
• Rate Limiting: Respects GitHub API rate limits
• Permission Errors: Clear error messages and suggestions
• Invalid Input: Input validation and correction prompts

Logging and Output

Log Levels

• Info (ℹ️): General information messages
• Success (✅): Successful operations
• Warning (⚠️): Non-critical issues
• Error (❌): Critical failures
• Progress (🔄): Operation progress updates

Output Format

[EMOJI] [TIMESTAMP] [LEVEL] Message

Summary Report

Operation Summary
=================
Total repositories processed: 15
Successful removals: 12
Failed removals: 1
Skipped removals: 2
Success rate: 80%

Prerequisites

Required Tools

• curl - HTTP client for API requests
• jq - JSON processor for API responses

GitHub Token Permissions

• repo - Repository access (read/write)
• admin:org - Organization administration

Environment Requirements

• Bash 4.0 or higher
• Internet connectivity for GitHub API access
• Valid GitHub Personal Access Token

Security Considerations

Token Security

• Tokens are not stored or logged
• Input is hidden during token entry
• Tokens are validated before use

Operation Safety

• Interactive confirmations prevent accidental operations
• Detailed logging for audit trails
• Rollback information provided for manual recovery

Access Control

• Respects GitHub repository permissions
• Validates user access before operations
• Handles permission errors gracefully

Troubleshooting

Common Issues

1. Token Validation Fails: Ensure token has correct permissions
2. Repository Not Found: Check repository name and access permissions
3. User Not Found: Verify username spelling and existence
4. Rate Limiting: Wait for rate limit reset or use token with higher limits

Debug Mode

Enable verbose output by setting:

export DEBUG=1
./remove_user_interactive.sh

Integration

The tool integrates seamlessly with other ByteLyst DevOps tools:

• Can be called from bytelyst-cli.sh
• Supports JSON configuration files
• Compatible with existing workflow scripts
• Follows established logging and error handling patterns

Performance

Optimization Features

• Paginated API requests for large datasets
• Parallel processing where possible
• Efficient pattern matching algorithms
• Minimal memory footprint

Scale Considerations

• Handles hundreds of repositories efficiently
• Respects GitHub API rate limits
• Provides progress feedback for long operations
• Supports interruption and resumption