GitHub staying-evergreen-how-we-automat Released: Deep Architectural Breakdown

Executive Overview & Architectural Significance

The ongoing scaling challenges faced by modern enterprise engineering organizations invariably center on repository hygiene, access governance, and resource lifecycle management. As collaborations expand to incorporate external partners, contractors, and specialized professional services teams, repository owners face mounting operational friction. Manually auditing access lists, tracking project milestones, and archiving deprecated codebases rapidly devolves into brittle administrative overhead. To resolve these friction points internally within shared organizations where GitHub employees ("Hubbers") collaborate closely with enterprise clients, the core platform engineering team developed Evergreen. Evergreen functions as a native GitHub App designed to automate the cumbersome lifecycle mechanics of organization hygiene through disciplined, idempotent workflows.

Architecturally, Evergreen establishes a robust separation of concerns by delegating timekeeping and control mechanisms to a dedicated control repository, while executing distributed workflows natively via GitHub Actions and webhook event handlers. Operating under the strict security paradigm of "Fail Secure," the system guarantees that unresolved access reviews do not default to indefinite permission persistence; instead, unverified access rights are systematically revoked upon deadline expiration. Simultaneously, the framework adheres to a strict "Never Destroy Anything" mandate: repositories flagged for inactivity are archived rather than permanently deleted, ensuring recoverability while mitigating organization-wide surface area sprawl. By utilizing native primitives—such as custom properties, webhook events, and issue-ops interactions—Evergreen presents an exemplary blueprint for scalable enterprise repository management.

Core Enhancements & Developer Ergonomics

Evergreen introduces a sophisticated dual-workflow model focused on outside collaborator access reviews and stale repository detection. Every quarter, the system initiates automated evaluations that snapshot external collaborator permissions, prompting designated maintainers via localized checklist issues. Developers interact with the system using an intuitive "Issue-Ops" paradigm: maintainers simply verify required collaborators by checking corresponding boxes and closing the tracking issue. Upon receiving the issues.closed webhook event, Evergreen processes the selections, retains authorized identities, and automatically revokes stale permissions. Furthermore, the architecture implements permission safeguards by silently reopening issues and rejecting modifications attempted by unauthorized actors, ensuring that state transitions strictly originate from authorized personnel.

State persistence within Evergreen relies on a transparent, Git-native design where every repository's metadata is serialized into an individual JSON file residing within the control repository's state directory. This design choice eliminates the need for external databases or bespoke audit logging pipelines. Because state is committed directly to Git, the commit history itself functions as the canonical audit trail, allowing systems administrators and security auditors to execute git log to inspect historical state transitions. To streamline maintainer notifications, Evergreen evaluates ownership via a deterministic fallback chain: it first queries the repository's custom properties (evergreen_repo_owner) and, if absent, intelligently infers responsible stakeholders by analyzing recent issue and commit activity among internal engineering teams.

Architectural Comparison Matrix

Breaking Changes & Migration Caveats

Adopting the Evergreen automation framework introduces specific structural constraints that teams must accommodate within their organization workflows. First, repository maintainers must transition from ad-hoc manual permission adjustments to the structured Issue-Ops review model; bypassing the checklist issues will result in automated privilege revocation upon the hard expiration deadline. Second, organizations must provision a dedicated control repository configured with the appropriate GitHub App permissions (repo, admin:org, issues:write) to handle incoming webhooks and schedule dispatch events. While the architecture is backwards-compatible with existing repository structures, configuring custom properties (evergreen_repo_owner) is strongly recommended to ensure precise notification routing. Teams relying on legacy cron-based scripts must deprecate their custom polling mechanisms and migrate fully to the event-driven dispatch schedules detailed in the Evergreen controller configuration.

Step-by-Step Upgrade Guide

Migrating your organization to the Evergreen pattern involves provisioning the control plane, configuring scheduled actions, and deploying the webhook server.

1. Provision the Control Repository: Create a dedicated repository (e.g., org-evergreen-controller) and establish the initial directory hierarchy for state tracking:

   mkdir -p state/repos
   git commit -m "chore: initialize evergreen control repository structure"
   

2. Configure Scheduled GitHub Actions: Implement the quarterly dispatch workflows in your control repository under .github/workflows/evergreen-clock.yml to trigger repository evaluations:

   name: Evergreen Clock
   on:
     schedule:
       - cron: '0 0 1,8,16,23 * *'
   jobs:
     dispatch:
       runs-on: ubuntu-latest
       steps:
         - name: Trigger Repository Dispatch
           uses: actions/github-script@v6
           with:
     script: |
       await github.rest.repos.createDispatchEvent({
         owner: context.repo.owner,
         repo: context.repo.repo,
         event_type: 'evergreen_tick'
       });
   

3. Deploy the Webhook Controller: Deploy the lightweight Go webhook server within your containerized environment, ensuring the GITHUB_APP_PRIVATE_KEY and webhook secrets are securely injected via environment variables to process issues.closed and repository_dispatch events seamlessly.