Staying Evergreen: How we automated secure access and repo hygiene in a shared org

Evergreen is a GitHub App designed to automate repository hygiene in a shared organization, specifically for GitHub employees (Hubbers) working with customers and partners. The app addresses two key areas: outside collaborator access reviews and stale repository detection and archival.

The app operates on two design principles: fail secure and fail closed. If no one responds to an access review, the app revokes all access rather than leaving it in place. Additionally, the app never deletes repositories or their contents. Archived repositories are recoverable, and all access changes are documented within the repository's tracking issue, allowing for easy reversal of mistakes.

Under the hood, Evergreen relies on a small Go webhook server running in a container, supplemented by several GitHub features such as scheduled actions, webhooks, issues, custom properties, and plain files in a repository. A dedicated controller repo acts as Evergreen's clock and memory, utilizing four scheduled GitHub Actions workflows that fire on a quarterly basis. These workflows perform the following tasks:

1. Stale repo review: The app identifies repositories with no recent human activity and opens a warning issue for each one.

2. Access review: The app captures a snapshot of outside collaborators for each repository and opens a checklist issue per repo.

3. Stale repo cleanup: After the grace period, the app archives repositories still deemed stale.

4. Access cleanup: The app revokes access for any review left unanswered two weeks before its cleanup run, with a hard grace period to prevent premature deletions.

Evergreen tracks every repository's status as a JSON file committed to the controller repo under state/repos/ .json. This state file contains information such as who had access, when the review opened, the deadline, who made the decision, and what happened. This approach provides an easy-to-access audit trail without the need for a separate database or audit pipeline.

The app communicates through issues inside each repository. When an access review begins, every repository receives a checklist issue that requires the review team to check boxes for collaborators to retain. Once closed, Evergreen listens for the issues.closed webhook event, retains the checked collaborators, and revokes the rest. A receipt comment is then posted, detailing exactly what was kept and what was removed. Access to close an access review issue is restricted to authorized Hubbers to maintain proper governance.

To determine which Hubbers own a repository, Evergreen employs a fallback chain. If a repository sets an evergreen_repo_owner custom property (a @user or @org/team), that value is used. Otherwise, the app looks at recent issue and commit authors and notifies Hubbers who are part of the access review team working on that repo. This approach ensures that the right people are notified without the need for maintaining a spreadsheet of repository ownership.