Skip to content

README.md

Latest commit

 

History

History
90 lines (66 loc) · 3.44 KB

README.md

File metadata and controls

90 lines (66 loc) · 3.44 KB

GitHub Organization Migration CLI

A lightweight Python-based CLI tool to automate the process of exporting GitHub Organization repositories. This tool fetches all repositories from a specific organization, initiates a migration, monitors its status, and downloads the final archive.

Sources used:

This code was made as a one-time use script. It was mostly written using Gemini in the interest of saving time in a time-constrained scenario. It been run and works.

🚀 Features

  • Automated Discovery: Fetches up to 100 repositories automatically from the target organization.
  • Migration Management: Starts an authenticated migration with repository locking enabled.
  • Status Tracking: Check the real-time status of your migration via the CLI.
  • Secure Downloads: Streams the migration .tar.gz archive directly to your local machine once ready.
  • Secret Management: Uses .env files to keep your GitHub Personal Access Token (PAT) secure.

🛠 Prerequisites

  1. Python 3.7+
  2. GitHub Personal Access Token (PAT):
    • For classic tokens, you need the repo and admin:org scopes.
    • For fine-grained tokens, you need Organization Migrations (read/write) and Organization Metadata (read-only) permissions.

📦 Installation

  1. Clone or save the script to your local machine.
  2. Install dependencies: 
    pip install requests python-dotenv
  3. Configure Environment Variables: Create a .env file in the root directory: 
    GITHUB_TOKEN=your_ghp_token_here
GITHUB_ORG=chaoss

📖 Usage

The tool is divided into three main commands: start, status, and download.

1. Start a Migration

This command fetches all repositories in the org and triggers the GitHub migration engine.

uv run python3 backup.py start
  • Note: This script is configured to lock repositories (making them read-only) during the migration.
  • Output: This will provide you with a Migration ID (e.g., 54321). Save this ID.

2. Check Migration Status

GitHub needs time to package the data. Use the ID from the previous step to check progress.

uv run python3 backup.py status 54321
  • Wait until the status changes from pending or exporting to exported.

3. Download the Archive

Once the status is exported, download the final .tar.gz file.

uv run python3 backup.py download 54321
  • The file will be saved as migration_ORG_ID.tar.gz in your current directory.

4. Unlock the repos

Once the download is complete, the repos that were locked for the migration need to be unlocked

uv run python3 backup.py unlock 54321

⚠️ Important Notes

  • Archive Expiration: GitHub stores migration archives for 7 days. After that, they are deleted, and you must start a new migration.
  • Pagination: This script currently fetches the first 100 repositories. If your organization has more, the script will need to be updated to handle API pagination loops.
  • Rate Limits: Be mindful of GitHub API rate limits if running this repeatedly on very large organizations.

📝 License

This project is licensed under the MIT License. Use it at your own risk—especially the lock_repositories feature!