Maintenance Flows

This document outlines the maintenance workflows used for managing example repositories and their associated infrastructure.

Overview

The Open Deployments project maintains example repositories that demonstrate deployment patterns. Each example includes:

Source code - Working application with deployment configuration
GitHub Actions workflows - Automated CI/CD pipelines
Infrastructure as Code - SST configuration for cloud resources
Documentation - Guides and setup instructions

Example Repository: Next.js Lambda with GitHub Actions

Repository Structure


nextjs-lambda-github-actions/
├── .github/
│   └── workflows/
│       ├── production.yml      # Deploy infrastructure
│       └── remove-production.yml # Remove infrastructure
├── app/                        # Next.js application
├── sst.config.ts              # SST infrastructure configuration
└── package.json               # Dependencies and scripts

Deployment Workflow

Automatic Deployment

The deployment workflow (production.yml) automatically triggers on pushes to the main branch:

Setup Environment - Installs Node.js, pnpm, and dependencies
Configure AWS - Sets up AWS credentials from GitHub secrets
Deploy Infrastructure - Runs pnpm sst deploy --stage=production

Required GitHub secrets:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
CLOUDFLARE_API_TOKEN (optional, for custom domains)
CLOUDFLARE_DEFAULT_ACCOUNT_ID (optional)
CLOUDFLARE_EMAIL (optional)

Manual Infrastructure Removal

The removal workflow (remove-production.yml) requires manual trigger with confirmation:

Navigate to Actions tab in GitHub repository
Select “Remove Production Infrastructure” workflow
Click “Run workflow”
Type DESTROY in the confirmation field
Execute the workflow

Safety Features

The removal workflow includes multiple safety measures:

Manual trigger only - Prevents accidental execution
Confirmation required - Must type “DESTROY” to proceed
Environment protection - Uses Production environment rules
Clear validation - Workflow fails if confirmation is incorrect

Infrastructure Management

SST Configuration

The sst.config.ts file defines the infrastructure:


export default $config({
  app(input) {
    return {
      name: "nextjs-lambda-github-actions",
      removal: input?.stage === "production" ? "retain" : "remove",
      protect: ["production"].includes(input?.stage),
      home: "aws",
      providers: {
        aws: { region: "us-east-1" },
        cloudflare: "latest",
      },
    };
  },
  async run() {
    new sst.aws.Nextjs("NextjsLambdaGithubActionsWebsite", {
      domain: isProduction ? {
        name: "your-domain.com",
        dns: sst.cloudflare.dns(),
      } : undefined,
    });
  },
});

Stage Management

Production stage - Protected with retention policies
Development stages - Auto-cleanup enabled
Domain configuration - Optional custom domain setup

Workflow Maintenance

Adding New Examples

When creating new example repositories:

Copy base structure from existing examples
Update repository name in all configuration files
Configure GitHub secrets for the new repository
Test deployment workflow before making repository public
Document in Open Deployments website

Updating Existing Examples

For updates to existing examples:

Test changes locally before pushing
Review infrastructure changes in SST config
Update documentation if workflow changes
Verify GitHub Actions still work correctly

Security Considerations

Secrets management - Use GitHub secrets, never commit credentials
Environment protection - Enable branch protection and environment rules
Least privilege - AWS IAM roles with minimal required permissions
Regular rotation - Rotate AWS access keys periodically

Troubleshooting

Common Issues

Deployment Failures:

Check AWS credentials and permissions
Verify SST configuration syntax
Review CloudFormation stack errors in AWS console

GitHub Actions Failures:

Validate required secrets are configured
Check Node.js version compatibility
Review pnpm lockfile for dependency issues

Infrastructure State Issues:

Use sst refresh to sync state
Check for manual AWS resource changes
Review SST state in .sst/ directory

Recovery Procedures

If infrastructure gets into an inconsistent state:

Manual cleanup - Remove resources via AWS console
State reset - Delete .sst/ directory and redeploy
Fresh deployment - Create new stage and migrate resources