bytelyst-devops-tools/README_remove_user_script.md

# GitHub User Removal Script

A comprehensive script to remove a specified user from all repositories matching a prefix pattern under a given GitHub username or organization.

## Features

- ✅ **Flexible Filtering**: Support for various repository prefix patterns including wildcards
- ✅ **Dry Run Mode**: Test operations without making actual changes
- ✅ **Verbose Logging**: Detailed output for debugging and monitoring
- ✅ **Progress Tracking**: Real-time progress updates during processing
- ✅ **Error Handling**: Robust error handling with detailed HTTP status reporting
- ✅ **Statistics**: Comprehensive summary of operations performed
- ✅ **Auto-detection**: Automatically detects if the root is a user or organization

## Requirements

- `bash` (version 4.0+)
- `curl` 
- `jq`
- Valid GitHub Personal Access Token with `repo` and `admin:org` permissions

## Usage

```bash
./remove_user_from_repos.sh -t TOKEN -r ROOT_USER -u USER_TO_REMOVE -p REPO_PREFIX [OPTIONS]
```

### Required Parameters

| Parameter | Description |
|-----------|-------------|
| `-t, --token TOKEN` | GitHub Personal Access Token |
| `-r, --root ROOT_USER` | Root GitHub username or organization |
| `-u, --user USER_TO_REMOVE` | Username to remove from repositories |
| `-p, --prefix REPO_PREFIX` | Repository name prefix pattern |

### Optional Parameters

| Parameter | Description |
|-----------|-------------|
| `-d, --dry-run` | Show what would be done without making changes |
| `-v, --verbose` | Enable verbose logging |
| `-h, --help` | Show help message |

## Repository Prefix Patterns

| Pattern | Description | Example Matches |
|---------|-------------|-----------------|
| `"bytelyst-"` | Repos starting with 'bytelyst-' | `bytelyst-web`, `bytelyst-api` |
| `"*api*"` | Repos containing 'api' | `web-api`, `api-service`, `my-api-v2` |
| `"*"` | All repositories | All repos in the organization/user |
| `"web-app"` | Repos starting with 'web-app' | `web-app-frontend`, `web-app-v2` |

## Examples

### 1. Remove user from all repositories starting with 'bytelyst-'
```bash
export GITHUB_TOKEN="your_token_here"
./remove_user_from_repos.sh -t "$GITHUB_TOKEN" -r "saravanakumardb" -u "i-ayushh18" -p "bytelyst-"
```

### 2. Dry run - Remove user from all repositories (preview mode)
```bash
./remove_user_from_repos.sh -t "$GITHUB_TOKEN" -r "myorg" -u "olduser" -p "*" --dry-run
```

### 3. Remove user with verbose logging
```bash
./remove_user_from_repos.sh -t "$GITHUB_TOKEN" -r "myorg" -u "olduser" -p "project-" --verbose
```

### 4. Remove user from repositories containing 'api'
```bash
./remove_user_from_repos.sh -t "$GITHUB_TOKEN" -r "myorg" -u "developer123" -p "*api*"
```

## Output Example

```bash
GitHub User Removal Script
============================================================
ℹ️  Root user/organization: saravanakumardb
ℹ️  User to remove: i-ayushh18
ℹ️  Repository prefix: bytelyst-
✅ Token validated (authenticated as: saravanakumardb)

Repository Discovery
============================================================
✅ Found 23 repositories

Filtering Repositories
============================================================
✅ Found 4 repositories matching prefix 'bytelyst-'

Processing Repositories
============================================================
Progress: [100%] 4/4 repositories processed
✅ Successfully removed i-ayushh18 from saravanakumardb/bytelyst-web-app

Operation Summary
============================================================
Repositories scanned: 23
Repositories matching prefix: 4
Repositories where user was collaborator: 1

Successful removals: 1
Already removed: 0
Failed removals: 0
Success rate: 100%

✅ Operation completed successfully!
```

## Creating GitHub Token

1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens
2. Click "Generate new token"
3. Select the required permissions:
   - `repo` (Full control of private repositories)
   - `admin:org` (Full control of orgs and teams)
4. Set appropriate expiration date
5. Generate and copy the token

## Security Best Practices

- Store tokens as environment variables: `export GITHUB_TOKEN="your_token"`
- Never commit tokens to version control
- Use fine-grained tokens with minimal required permissions
- Regularly rotate tokens
- Use `--dry-run` first to verify operations

## Error Handling

The script handles various error scenarios:

- **Invalid tokens**: Authentication validation before operations
- **Missing repositories**: Graceful handling of non-existent repos
- **Insufficient permissions**: Clear error messages for access issues
- **Network issues**: Retry logic for transient failures
- **Invalid users/orgs**: Proper detection and error reporting

## Exit Codes

- `0`: Success - All operations completed successfully
- `1`: Failure - One or more operations failed (details in summary)

## Troubleshooting

### Common Issues

1. **"Invalid or expired GitHub token"**
   - Check token validity
   - Ensure token has required permissions

2. **"Access forbidden for repository"**
   - Token may lack admin permissions for the repository
   - Repository may be archived or have restricted access

3. **"Could not fetch repositories"**
   - User/organization name may be incorrect
   - Token may lack appropriate access

### Debug Mode

Use `--verbose` flag to see detailed operation logs:
```bash
./remove_user_from_repos.sh -t "$TOKEN" -r "user" -u "target" -p "*" -v
```

## Integration Examples

### CI/CD Pipeline
```yaml
- name: Remove user from repositories
  run: |
    ./remove_user_from_repos.sh \
      -t "${{ secrets.GITHUB_TOKEN }}" \
      -r "${{ vars.ORG_NAME }}" \
      -u "${{ vars.USER_TO_REMOVE }}" \
      -p "${{ vars.REPO_PREFIX }}"    
```

### Batch Processing
```bash
#!/bin/bash
users=("user1" "user2" "user3")
for user in "${users[@]}"; do
  ./remove_user_from_repos.sh -t "$TOKEN" -r "myorg" -u "$user" -p "*"
done
```

## License

This script is provided as-is for repository management purposes. Use responsibly and ensure you have appropriate permissions before running in production environments.