Skip to content

Home

Jump to bottom
genesluna edited this page Mar 2, 2026 · 5 revisions

K8s Ephemeral Environments

Automated preview environments for every Pull Request.

This platform automatically creates isolated Kubernetes environments when you open a PR, gives you a preview URL to share with your team, and cleans everything up when the PR is closed. No manual setup, no environment conflicts, just instant feedback on your changes.

Why Use This Platform?

Benefit Description
Instant Previews Get a working URL within minutes of opening a PR
Complete Isolation Each PR has its own app instance and database - no conflicts
Zero Maintenance Environments are created and destroyed automatically
Built-in Observability Centralized logs and metrics with pre-built Grafana dashboards
Database Support PostgreSQL, MariaDB, MongoDB, Redis, and MinIO out of the box

Quick Start Overview

Add ephemeral environments to your repository in 3 simple steps:

1. Create Configuration File

Add k8s-ee.yaml to your repo root:

projectId: myapp
app:
  healthPath: /health
databases:
  postgresql: true

2. Add Workflow

Create .github/workflows/pr-environment.yml:

name: PR Environment

on:
  issue_comment:
    types: [created]
  pull_request:
    types: [opened, reopened, synchronize, closed]

permissions:
  contents: read
  packages: write
  pull-requests: write
  security-events: write

jobs:
  pr-environment:
    if: |
      github.event_name == 'pull_request' ||
      (github.event_name == 'issue_comment' &&
       github.event.issue.pull_request &&
       (startsWith(github.event.comment.body, '/deploy-preview') ||
        startsWith(github.event.comment.body, '/destroy-preview')))
    uses: koder-cat/k8s-ephemeral-environments/.github/workflows/pr-environment-reusable.yml@main
    with:
      pr-number: ${{ github.event.pull_request.number || 0 }}
      pr-action: ${{ github.event.action || '' }}
      head-sha: ${{ github.event.pull_request.head.sha || '' }}
      head-ref: ${{ github.head_ref || '' }}
      repository: ${{ github.repository }}
      comment-body: ${{ github.event.comment.body || '' }}
      comment-id: ${{ github.event.comment.id || 0 }}
      issue-number: ${{ github.event.issue.number || 0 }}
    secrets: inherit

3. Add a Dockerfile

Ensure your app has a Dockerfile. The platform builds ARM64 images automatically.

That's it! Open a PR to get your preview URL.

See Quick Start for detailed instructions and Prerequisites for requirements.

How It Works

By default, environments are created automatically for every PR. If you prefer to create environments only when needed, you can use on-demand mode where environments are triggered by a /deploy-preview comment. See On-Demand Environments for details.

Developer opens PR
        |
        v
GitHub Actions triggered (automatic or on-demand via /deploy-preview)
        |
        v
New environment created (app + database)
        |
        v
Preview URL posted as PR comment
        |
        v
Team reviews and tests
        |
        v
PR merged or closed
        |
        v
Environment automatically destroyed

Navigation

Getting Started

User Guides

Operations

Project Status

Phase Status Description
Phase 1 Complete Core platform on single VPS
Phase 1.5 Complete Performance, testing, security improvements
Phase 2 Complete Simplified onboarding with reusable workflows
Phase 3 Planned Migration to AWS EKS

Supported Databases

Database Use Case
PostgreSQL Primary relational database
MariaDB Alternative relational database
MongoDB Document storage, audit logging
Redis Caching, rate limiting
MinIO S3-compatible object storage

Current Limitations

  • Only public repositories are supported
  • Single VPS deployment (ARM64 architecture)
  • Maximum 5 simultaneous PR environments

License

This project is dual-licensed under AGPL-3.0 (free, open source) and a Commercial License for organizations that need proprietary terms.

See Licensing for details.

Home

Getting Started

User Guides

Troubleshooting

Operations

Architecture

Demo Applications

Development

Clone this wiki locally