Automating Repository Hygiene and Secure Access with Evergreen
GitHub's internal tool automates collaborator reviews and archival using native platform features.
1The Challenge of Manual Hygiene
Managing outside collaborators in a large organization creates significant administrative overhead for repository owners. Tracking access permissions, identifying stale projects, and performing manual cleanup becomes increasingly difficult as project volume grows. GitHub faced this scaling issue with thousands of Hubbers collaborating on trials, necessitating a more robust, automated system for organization maintenance.
2Introducing the Evergreen Framework
Evergreen is a custom GitHub App designed to automate organization hygiene through two primary workflows. It performs quarterly reviews of outside collaborator access and identifies stale repositories lacking human activity. The system prioritizes security by defaulting to access revocation if reviews remain unanswered, ensuring that permissions do not persist indefinitely without explicit validation.
3Core Design Principles Applied
The system follows two strict design principles: fail secure and never destroy data. If a review deadline passes without response, access is automatically revoked to maintain security. Conversely, the tool never deletes repositories; it archives them, ensuring all content remains recoverable. Every access change is documented within repository issues for easy auditing.
4Orchestrating Workflows via GitHub
Evergreen operates as a Go webhook server using native GitHub features like Actions, webhooks, and custom properties. A dedicated controller repository acts as the system's clock and memory. Four scheduled workflows trigger repository_dispatch events on a quarterly cadence, managing the lifecycle of access reviews and archival processes without requiring any exotic external infrastructure.
5State Management and Audit Trails
The system tracks repository status as JSON files committed directly to the controller repository. This approach turns the git commit history into a permanent, searchable audit trail. By avoiding separate databases, engineers can simply use git log to investigate why access was revoked, providing transparency without the complexity of a bespoke audit pipeline.
6Leveraging IssueOps for Interaction
Evergreen communicates through checklist issues created within each repository. Repository owners simply check boxes for collaborators who should retain access and close the issue to trigger the update. The app listens for the issues.closed webhook, processes the changes, and posts a receipt comment detailing exactly which permissions were modified or removed.
7Intelligent Notification and Ownership
To ensure the right people respond, Evergreen uses a fallback chain to identify repository owners. It first checks for a custom property, then analyzes recent commit and issue authors. This eliminates the need for maintaining manual spreadsheets of ownership, automatically pinging the relevant Hubbers who are actively working within the specific repository context.
8Scaling with Platform Constraints
Rolling out automation to an organization with over 1,400 employees requires respecting GitHub's secondary rate limits. Evergreen processes repositories in batches and spaces out content-creating calls to stay under the 80 requests per minute limit. This proactive pacing ensures the system remains stable even when managing thousands of repositories across the entire organization.
9Lessons for Sustainable Automation
Effective automation should feel considerate rather than disruptive. By using native primitives like issues and git history, organizations can build robust tools that meet users where they already work. The key is making the safe path the default, providing clear escape hatches, and ensuring that routine hygiene becomes a predictable, scheduled background process.
Original article: The GitHub Blog — Automating Repository Hygiene and Secure Access with Evergreen