Managing a sprawling digital infrastructure is a challenge that often leads to a silent, mounting technical debt: the accumulation of unused repositories and forgotten access permissions. For large organizations, the administrative burden of tracking who has access to which repository—and whether that repository is still serving a purpose—can quickly outpace manual oversight. At GitHub, engineers faced this exact dilemma while facilitating collaborations between internal staff, known as "Hubbers," and external partners during product trials and professional services engagements. To solve this, the team developed "Evergreen," a custom GitHub App designed to automate organizational hygiene by leveraging native platform features.
The core challenge for any repository owner is the maintenance cycle. Confirming access requirements, adjusting permissions as project scopes evolve, and archiving repositories that have reached the end of their lifecycle are essential tasks, yet they are frequently deferred in favor of more immediate development work. As a project grows, this manual housekeeping becomes increasingly complex, creating a paradox where the most active organizations are often the ones with the most cluttered, insecure environments.
Meeting the Evergreen Philosophy
Evergreen operates on two primary design principles that prioritize safety and accountability. The first is "fail secure." In the context of access management, this means that if an authorized user does not respond to a review request regarding a collaborator’s access, the system does not default to leaving that access in place. Instead, it revokes the access. The safest outcome is the default outcome, ensuring that external collaborators are not granted perpetual, unchecked access to internal assets.
The second principle is "never destroy anything." While Evergreen is designed to clean up, it is strictly forbidden from permanently deleting repositories or their contents. By focusing on archiving, the system ensures that data remains recoverable if a mistake is made. Furthermore, because every access change is meticulously documented within a repository’s tracking issue, reverting an incorrect action is a straightforward process, often aided by modern tools like Copilot to quickly generate the necessary commands.
The Architecture of Automated Choreography
Under the hood, Evergreen is a lightweight Go webhook server hosted within a container. However, its effectiveness lies not in complex proprietary code, but in the intelligent "choreography" of standard GitHub features. By utilizing GitHub Apps, scheduled Actions, webhooks, and custom repository properties, the developers avoided creating an exotic, high-maintenance internal tool.
The system functions through a "controller repository," which serves as both the clock and the memory for the entire organization. A series of scheduled GitHub Actions workflows triggers events on a quarterly basis. These events dictate a rhythm of maintenance: the first day of the quarter focuses on identifying stale repositories that lack recent human activity; the eighth day initiates an access review by snapshotting current outside collaborators; the sixteenth day triggers the archival process for repositories that have remained stagnant past their grace period; and the twenty-third day handles the final revocation of access for any reviews that went unanswered.
This timeline is intentionally deliberate. Reviews are opened two weeks before any automated action takes place, and a hard grace period is built into the logic to ensure that a stray manual override or a temporary error cannot trigger an accidental deletion or revocation. The system also supports manual triggers, allowing administrators to initiate any phase of the process on demand when specific circumstances require immediate intervention.
Transparency and the Audit Trail
A defining feature of Evergreen is its reliance on Git as a source of truth. The system tracks the status of every repository via individual JSON files stored within the controller repository. Each file acts as a comprehensive record, containing the repository ID, the last time it was accessed, the status of the access review, the deadline, the identity of the person who approved or denied access, and the corresponding tracking issue number.
Because this state information is stored as files within a Git repository, the commit history essentially becomes the audit trail. This eliminates the need for a separate database or a complex, custom-built logging pipeline. If an administrator needs to investigate why a specific user lost access to a repository three months ago, they can simply inspect the commit history of the relevant state file. This approach transforms standard version control into a powerful management tool, providing complete visibility into decision-making without adding operational overhead.
Issue-Driven Operations
Evergreen interacts with the organization through the very medium developers use daily: GitHub Issues. When an access review begins, the system opens a checklist issue in the affected repository. This issue acts as the primary interface for repository owners, listing all external collaborators and their current permission levels.
The interaction model is designed to be as frictionless as possible: owners simply check the boxes for the individuals who require continued access and then close the issue. Upon closing, the system processes the request by parsing the checkboxes, retaining the selected access, and automatically revoking the rest. A final receipt comment is posted to the issue, detailing exactly which permissions were preserved and which were removed, providing a clear record of the outcome.
To prevent unauthorized tampering, Evergreen includes a robust security layer. It monitors the identity of whoever closes an access review issue. If an unauthorized user attempts to resolve a review, the application will automatically reopen the issue and provide a notification explaining why the action was rejected. This ensures that only authorized personnel can make decisions regarding the security and access profile of a repository.
Solving the Ownership Problem
A common hurdle in organizational maintenance is determining who actually owns a repository. In large companies, institutional knowledge often gaps when team members move roles or leave. Evergreen addresses this by utilizing a fallback notification chain. It first attempts to identify the official owners of a repository; if that information is missing or ambiguous, it cascades through other organizational signals to ensure that the notification reaches the right people. This system removes the need for human administrators to maintain static, error-prone spreadsheets of ownership, ensuring that the right stakeholders are always pinged when a review is due.
Resilience and the "Fail Closed" Strategy
The developers of Evergreen were particularly careful to address potential points of failure, such as transient API errors. If the system attempted to revoke access and encountered a network error, it would be dangerous to mark the entire process as "done." To prevent this, Evergreen operates on a "fail closed" basis. If any part of a removal process encounters an error, the review remains pending, the issue stays open, and the system schedules a retry for the remaining tasks. It only marks a review as finalized once every intended change has been successfully confirmed.
A Considerate User Experience
Automated systems often suffer from being intrusive or "noisy," functioning like a malfunctioning alarm that causes more frustration than safety. The team behind Evergreen prioritized making the experience feel considerate. They avoided sending unnecessary pings, ensured that notifications were contextual and helpful, and designed the process to feel like a standard part of the developer workflow rather than an external imposition.
The rollout of such a system across an organization with thousands of employees required extreme caution. The team utilized a "dry-run" mode, which allowed the system to log every action it intended to take without actually changing any permissions. This period of observation was critical, as it allowed engineers to "read the tea leaves" of the logs to ensure the logic was sound before allowing the system to take control. Additionally, they leaned heavily on observability, using Splunk to track structured logs and identify edge cases—such as repositories with disabled issues or unusual permission structures—that might have caused the automation to behave unexpectedly.
By integrating these practices, GitHub has created a framework that turns routine maintenance from a dreaded, deferred chore into a seamless, automated process. The lesson for other organizations is that effective governance does not require building massive, bespoke platforms; it requires the disciplined application of existing tools to create a sustainable, transparent, and, above all, "evergreen" environment.
