Terraform Ephemeral Environments with GitHub Actions (For Test env)

This project demonstrates how to use Terraform + GitHub Actions + AWS OIDC to create ephemeral environments for every Pull Request (PR).

The benefits:

• Faster feedback – every PR spins up a live testable environment.
• Isolation – no more shared staging collisions.
• Cost control – resources are cleaned up automatically, avoiding cloud bill sprawl.
• Governance – every resource is tagged to its PR for traceability.

This approach makes infrastructure testing safe, efficient, and cost-aware by treating environments as short-lived features rather than permanent setups.

When a contributor opens a PR that contains new Terraform resources (like EC2, S3, etc.), the pipeline will:

1. Automatically create an isolated environment named after the PR number (e.g., pr-42).
2. Deploy resources with that PR number tagged.
3. When the PR is merged or closed, the destroy pipeline automatically runs and cleans up all resources tied to that PR.

---

How It Works (Pipeline)

PR Create – Ephemeral Env

• Trigger: when a PR is opened/reopened/synchronized
• Steps:
  1. Checkout repo
  2. Authenticate to AWS via OIDC
  3. Run terraform init using the backend (S3 + DynamoDB)
  4. Create/select a workspace named pr-<number>
  5. Run terraform apply -auto-approve -var="pr_number=<number>"

PR Destroy – Ephemeral Env

• Trigger: when a PR is closed
• Steps:
  1. Checkout repo
  2. Authenticate to AWS via OIDC
  3. Run terraform init
  4. Select the workspace pr-<number>
  5. Run terraform destroy -auto-approve -var="pr_number=<number>"
  6. Delete the workspace

---

Tutorial: Using This Project

1. Bootstrap the Repo (once, you can add it to gitignor)

In the main branch, include a bootstrap module that creates:

• An S3 bucket for state
• A DynamoDB table for state locking
• An IAM role for GitHub OIDC

This bootstrap step outputs a backend.tf file like:

terraform {
  backend "s3" {
    bucket         = "terraform-ephemeral-envs-state-24a14f93"
    key            = "envs/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-ephemeral-envs-locks-24a14f93"
    encrypt        = true
  }
}

Then commit:

• backend.tf
• versions.tf
• providers.tf

to your main branch.

---

2. Create a Feature Branch

• Developers or testers create a new branch (for example):

git checkout -b feature/test-s3

• Add a new Terraform resource, for example an S3 bucket (see the branch feature/test-s3)

Commit and push the branch.

---

3. Open a PR

• Open a PR against main.
• The PR Create – Ephemeral Env workflow runs automatically.
• Terraform provisions the bucket with PR=<number> as a tag.

---

4. Validate & Merge

• Reviewers can approve the request once the tester has completed their work.
• Once testing is done → merge or close the PR.

---

5. Automatic Cleanup

• The PR Destroy – Ephemeral Env workflow runs.
• All resources tied to that PR (workspace + tags) are destroyed.
• No orphaned resources.

---

🔎 Example Flow

1. PR #10 opened → creates S3 bucket test-pr-10
2. PR #11 opened → creates EC2 instance ephemeral-pr-11
3. PR #10 merged → bucket destroyed
4. PR #11 closed → EC2 destroyed

Every PR manages its own short-lived environment.

---

With this setup, project managers and teams get full control over testing resources without worrying about cost sprawl or forgotten environments.