cs249r_book/book/tools/scripts/docs/WORKFLOW_CLEANUP.md

GitHub Workflow Runs Cleanup

This script helps clean up old GitHub workflow runs while keeping a configurable number of recent runs per workflow. It's particularly useful when you have many failed runs from debugging.

Quick Start

1. Get a GitHub Personal Access Token

   • Go to https://github.com/settings/tokens
   • Create a token with actions:write and repo scopes
   • Save the token securely

2. Set up the token

   # Option 1: Set environment variable (recommended)
   export GITHUB_TOKEN="your_token_here"
   
   # Option 2: Use --token flag each time
   

3. Preview what would be cleaned up

   python3 tools/scripts/cleanup_workflow_runs.py --summary
   python3 tools/scripts/cleanup_workflow_runs.py --dry-run --keep 5
   

4. Actually clean up workflow runs

   # Keep 5 most recent runs per workflow
   python3 tools/scripts/cleanup_workflow_runs.py --keep 5
   
   # Keep 10 most recent runs per workflow
   python3 tools/scripts/cleanup_workflow_runs.py --keep 10
   

Usage Examples

Show Current State

# See summary of all workflows and run counts
python3 tools/scripts/cleanup_workflow_runs.py --summary

Dry Run (Preview)

# See what would be deleted (keeping 5 runs per workflow)
python3 tools/scripts/cleanup_workflow_runs.py --dry-run --keep 5

# Preview cleanup for specific workflow
python3 tools/scripts/cleanup_workflow_runs.py --dry-run --workflow "quarto-build-container.yml" --keep 3

Actual Cleanup

# Clean all workflows, keep 5 most recent runs each
python3 tools/scripts/cleanup_workflow_runs.py --keep 5

# Clean specific workflow only, keep 3 runs
python3 tools/scripts/cleanup_workflow_runs.py --workflow "quarto-build-container.yml" --keep 3

# Keep more runs (10 per workflow)
python3 tools/scripts/cleanup_workflow_runs.py --keep 10

Advanced Usage

Environment Variables

# Set token once
export GITHUB_TOKEN="ghp_your_token_here"

# Override repository detection
export GITHUB_REPOSITORY="owner/repo"

Workflow-Specific Cleanup

You can target specific workflows by name or filename:

# By workflow filename
python3 tools/scripts/cleanup_workflow_runs.py --workflow "quarto-build-container.yml" --keep 3

# By workflow name
python3 tools/scripts/cleanup_workflow_runs.py --workflow "Quarto Build" --keep 3

Safety Features

• Dry Run Mode: Always preview before deleting
• Rate Limiting: Automatically handles GitHub API rate limits
• Error Handling: Graceful handling of API errors and permissions
• Auto-Detection: Automatically detects repository from git remote
• Confirmation: Clear output showing what was deleted

Troubleshooting

Permission Errors

❌ Permission denied. Check your token has 'actions:write' scope.

• Ensure your GitHub token has actions:write and repo scopes
• Re-generate token if needed

Rate Limiting

⚠️  Rate limit exceeded. Waiting 60 seconds...

• The script automatically waits for rate limit reset
• GitHub allows 5,000 API requests per hour for authenticated users

Repository Not Found

❌ Repository not specified and could not auto-detect from git

• Use --repo owner/repo flag
• Or ensure you're running from a git repository with GitHub remote

Script Options

Option	Default	Description
--keep	5	Number of recent runs to keep per workflow
--workflow	(all)	Target specific workflow by name or filename
--dry-run	false	Preview mode - don't actually delete
--summary	false	Show workflow summary and exit
--token	env var	GitHub personal access token
--repo	auto-detect	Repository in owner/repo format

Best Practices

1. Always dry run first: Use --dry-run to preview changes
2. Keep enough runs: Don't go below 3-5 runs to maintain debugging context
3. Target specific workflows: Use --workflow for problematic workflows
4. Regular cleanup: Run weekly/monthly to prevent accumulation
5. Monitor rate limits: Be aware of GitHub API limits for large cleanups