Automating Repository Hygiene and Secure Access with Evergreen
GitHub engineers built an automated system to manage collaborator access and archive stale repositories.
1The Challenge of Manual Hygiene
Managing outside collaborators in a large organization creates significant manual overhead for repository owners. Tracking permissions, deadlines, and follow-ups becomes increasingly difficult as projects scale. GitHub employees faced this exact problem when collaborating with customers on trials, leading them to develop Evergreen, an automated tool designed to maintain organization security.
2Core Functionality of Evergreen
Evergreen operates through two primary automated workflows: quarterly access reviews for outside collaborators and stale repository detection. The system flags repositories with no human activity, issues warnings, and eventually archives them if they remain untouched. This ensures that access permissions are regularly audited and inactive projects do not clutter the organization.
3Design Principles: Fail Secure
The system follows a strict fail-secure principle, meaning access is revoked by default if a review remains unanswered. To prevent accidental data loss, the tool never deletes repositories or their contents. Archived repositories remain fully recoverable, and every access change is documented within a tracking issue, allowing for easy restoration if needed.
4Architecture and Scheduling Logic
Evergreen runs as a Go webhook server within a container, utilizing native GitHub features like Actions, webhooks, and custom properties. A dedicated controller repository acts as the system's clock and memory. Four scheduled workflows fire quarterly, managing the lifecycle of repository reviews from initial flagging to final cleanup and access revocation.
5State Management via Git
Instead of using a separate database, Evergreen tracks repository status using JSON files committed directly to the controller repository. This approach turns the commit history into a permanent audit trail. By using git log, administrators can easily investigate why access was revoked for a specific user at any point in time.
6Interaction Through IssueOps
The tool communicates with users by opening checklist issues directly inside the relevant repositories. Owners simply check boxes for collaborators who should retain access and close the issue. Evergreen listens for the issues.closed webhook, processes the changes, and posts a receipt comment detailing exactly which permissions were kept or removed.
7Automated Ownership Resolution
Evergreen identifies the correct owners for notifications using a fallback chain. It first checks for a custom property named evergreen_repo_owner. If that is missing, the system analyzes recent issue and commit authors to ping the relevant Hubbers. This eliminates the need to maintain manual spreadsheets of repository ownership across the organization.
8Safe Rollout and Observability
To ensure a smooth deployment, the team utilized a dry-run mode that logged all intended actions without modifying permissions. They also integrated Splunk for structured logging to catch edge cases. By respecting GitHub's secondary rate limits through batched processing and intentional delays, the system maintains stability even when scaling across thousands of repositories.
9Scaling Routine Maintenance
Evergreen demonstrates that routine hygiene is best handled through automation rather than heroic cleanup sprints. By leveraging native platform primitives like issues and webhooks, organizations can create a predictable, secure environment. The key takeaway is to make the safe path the default path while providing users with clear, actionable communication.