Skip to main content

How to Adapt an Existing Project

High-level migration plan for moving existing projects to the EGI golden path.

Rollout Plan​

1. Inventory Current State​

Audit current deployment setup:

  • Document current pipelines and deployment targets
  • Identify secrets and configuration management
  • Map existing environments

2. Split Responsibilities​

Introduce the app and ops repo pattern:

  • App repo: Application code
  • Ops repo: Deployment intent

3. Introduce Deployment Intent Incrementally​

Phase the migration:

  • Start with the dev environment in the ops repo
  • Add staging and prod after stabilization
  • Test thoroughly at each stage

4. Standardize Secrets​

Move to standardized secrets management:

  • Move secrets to provider secret stores or ESO-backed stores
  • Remove all secrets from the repository
  • Create .env.example as reference

5. Align Identifiers and Versioning​

Standardize project identifiers:

  • Define the system identifier used across app repo, ops repo, and environments
  • Add documented version or release metadata
  • Use the generic SKU standard only if it fits the project

6. Add Production Readiness Signals​

Document readiness for future handoff:

  • Add or document a health endpoint
  • Add metrics where appropriate
  • Ensure logs are structured
  • Capture ownership, escalation, and backup expectations

7. Enforce Promotion Gates​

Add approval gates:

  • Add GitHub Environments with required approvals for prod
  • Configure automated promotions for dev and staging
  • Document approval workflow

8. Tagging and Milestones​

Apply project lifecycle tracking as needed by the team.

Acceptance Checklist​

  • Ops repo exists and drives dev deployment
  • Staging and prod promotions require PR and approval
  • Secrets are removed from repos
  • Versioning and environment identifiers are documented
  • Health, logging, and backup expectations are documented
  • Rollback procedure is documented and tested

Migration Considerations​

Common Challenges​

  • Legacy dependencies: May need containerization or an adapter layer
  • Secret sprawl: Audit all secrets before migration
  • Testing in production: Establish staging parity first

Risk Mitigation​

  • Keep the old pipeline active during migration
  • Use feature flags for gradual rollout
  • Document rollback to the legacy pipeline