gh-legacy

A powerful GitHub CLI tool for automatic repository ownership transfer to trusted beneficiaries after periods of inactivity.

🚀 Features

• Automatic Repository Transfer: Seamlessly transfer repository ownership to trusted users
• Flexible Inactivity Periods: Support for minutes, hours, days, weeks, months, and years
• Secure Token Management: Encrypted GitHub token storage with AES-256-CBC
• Email Notifications: Automated HTML email notifications with detailed instructions
• Heartbeat System: Reset inactivity timers with simple heartbeat commands
• Status Tracking: Comprehensive monitoring of all beneficiaries and transfer status
• Automated Scheduling: Set up automated access checking with cron jobs or task schedulers

📦 Installation

npm install -g gh-legacy

🔧 Quick Setup

1. Initialize the System

gh-legacy init

2. Configure GitHub Token

gh-legacy token

3. Add Beneficiaries

gh-legacy add-beneficiary <owner/repo> <email> <github-username> "<time-period>"

📖 Usage

Basic Commands

# Initialize the system
gh-legacy init

# Add a beneficiary (transfer after 6 months of inactivity)
gh-legacy add-beneficiary myusername/myproject [email protected] newowner "6 months"

# Send a heartbeat (reset inactivity timer)
gh-legacy heartbeat

# Check status of all beneficiaries
gh-legacy status

# Trigger access transfers manually
gh-legacy trigger-access

# Automatic trigger (for scheduling)
gh-legacy auto-trigger

Time Periods Supported

| Unit | Examples | |------|----------| | Minutes | "5 minutes", "30 minutes" | | Hours | "2 hours", "12 hours" | | Days | "7 days", "30 days" | | Weeks | "2 weeks", "4 weeks" | | Months | "3 months", "6 months" | | Years | "1 year", "2 years" |

🤖 Automation

Windows Task Scheduler

# Create a scheduled task to run daily at 9 AM
schtasks /create /tn "GH-Legacy Auto Trigger" /tr "C:\path\to\gh-legacy\run-auto-trigger.bat" /sc daily /st 09:00

Linux/Mac Cron Job

# Add to crontab (check daily at 9 AM)
0 9 * * * cd /path/to/gh-legacy && gh-legacy auto-trigger

PowerShell Scheduled Task

$action = New-ScheduledTaskAction -Execute "gh-legacy" -Argument "auto-trigger"
$trigger = New-ScheduledTaskTrigger -Daily -At 9AM
Register-ScheduledTask -TaskName "GH-Legacy Auto Trigger" -Action $action -Trigger $trigger

🔐 Security Features

• Encrypted Token Storage: GitHub tokens encrypted with AES-256-CBC
• Environment Variables: Email credentials stored securely
• No Plain Text: All sensitive data encrypted at rest
• Permission Validation: Ensures proper GitHub permissions before operations

📧 Email Notifications

Beneficiaries receive detailed HTML emails containing:

• Repository information and access details
• Step-by-step ownership transfer instructions
• Security considerations and best practices
• Contact information for support

🔄 How It Works

1. Setup Phase: Add trusted beneficiaries with their GitHub usernames and desired inactivity periods
2. Monitoring Phase: System tracks your last heartbeat (activity signal)
3. Transfer Phase: When inactivity threshold is reached, ownership transfer is initiated
4. Notification Phase: Beneficiaries receive detailed email notifications with transfer instructions

📋 Example Workflow

# 1. Install and initialize
npm install -g gh-legacy
gh-legacy init

# 2. Configure GitHub token
# Run the following command and enter your token when prompted:
gh-legacy token

# 3. Add trusted colleague as beneficiary
gh-legacy add-beneficiary myusername/important-project [email protected] colleague-username "6 months"

# 4. Send regular heartbeats
gh-legacy heartbeat

# 5. Monitor status
gh-legacy status

# 6. Set up automation (optional)
# Schedule gh-legacy auto-trigger to run daily

# 7. Automatic transfer occurs after 6 months of inactivity

🗃️ Transferred Repositories Archive

• When a repository is successfully transferred (ownership or admin access), it is removed from the main configuration and archived in a separate transferred.json file in your .gh-legacy directory.
• This archive includes the transfer status, timestamp, and a message log for each repo.
• You can view your transfer history and details by opening ~/.gh-legacy/transferred.json.

⚙️ Configuration

GitHub Token Setup

1. Generate a token at https://github.com/settings/tokens
2. Ensure it has repo permissions
3. Run gh-legacy token and enter your token when prompted

Email Notifications (Optional)

export GMAIL_USER="[email protected]"
export GMAIL_PASS="your-app-password"

🚨 Important Notes

• GitHub Permissions: Your token needs repository admin permissions
• Ownership Transfer: May require manual approval in some cases
• Regular Heartbeats: Send heartbeats regularly to prevent unwanted transfers
• Backup Strategy: Consider backing up your configuration regularly

🔧 Troubleshooting

Common Issues

| Issue | Solution | |-------|----------| | "Could not transfer ownership" | GitHub requires manual approval. Beneficiary can request transfer manually | | "Failed to send email" | Check Gmail credentials and app password setup | | "No configuration found" | Run gh-legacy init first | | "Token not found" | Run gh-legacy token and enter your token |

Debug Commands

# Check current status
gh-legacy status

# Force trigger access (with confirmation)
gh-legacy trigger-access

# Automatic trigger (no confirmation)
gh-legacy auto-trigger

# List all beneficiaries
gh-legacy list

# Resend emails with updated template
gh-legacy resend-email

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Octokit for GitHub API integration
• Uses Commander.js for CLI functionality
• Email notifications powered by Nodemailer

📞 Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• Email: [email protected]

Made with ❤️ for the GitHub community