Ephemeral DigitalOcean GitHub Runner

This repository provides a reusable GitHub Actions workflow that creates a temporary (ephemeral) GitHub Actions runner on DigitalOcean, runs a job on it, and automatically deletes the droplet after the job completes.

This approach is ideal for:

• Cost-efficient CI/CD
• Clean, isolated build environments
• Heavy or untrusted workloads
• Self-hosted runner scaling

---

🚀 What This Workflow Does

1. Creates a DigitalOcean droplet
2. Registers it as a GitHub Actions runner
3. Runs your job on that runner
4. Deletes the droplet (state: absent)
5. Leaves no running infrastructure behind

---

🔄 Workflow Lifecycle

create-runner  →  run-job  →  destroy-runner
     │               │              │
     │               │              └─ Deletes droplet
     │               └─ Job runs on ephemeral VM
     └─ Creates VM + GitHub runner

---

✅ Key Features

• ✔ Ephemeral (one-time) runner per job
• ✔ No idle VMs
• ✔ Automatic cleanup using DigitalOcean API
• ✔ Works with any shell command
• ✔ Safe cleanup using if: always()

---

📂 Workflow File

The reusable workflow is defined at:

.github/workflows/ephemeral-do-runner.yml

---

🔧 Inputs

Input Name	Required	Default	Description
do_size	No	s-1vcpu-1gb	DigitalOcean droplet size
do_region	No	nyc1	DigitalOcean region
job_command	Yes	—	Shell command(s) to run on the runner

---

🔐 Secrets

Secret Name	Required	Description
DIGITAL_OCEAN_ACCESS_TOKEN	Yes	DigitalOcean API token with droplet permissions

---

🧪 Example Usage

name: Build on Ephemeral Runner

on:
  workflow_dispatch:

jobs:
  build:
    uses: ./.github/workflows/ephemeral-do-runner.yml
    with:
      job_command: |
        echo "Running on ephemeral DO runner"
        uname -a

---

🛡️ Cleanup & Leak Prevention

• The workflow uses if: always() to ensure the destroy step runs even if the job fails
• The droplet is deleted, not stopped
• No manual cleanup required

⚠️ In rare cases (GitHub outage, control runner failure), cleanup could be skipped.
For maximum safety, consider adding VM self-shutdown logic inside the runner.

---

🧠 Best Practices

• Use small droplet sizes for CI jobs
• Prefer short-lived workloads
• Avoid storing persistent data on the runner
• Treat the runner as disposable

---

📌 Notes

• Requires a control runner (self-hosted, control-runner) to create and delete droplets
• The ephemeral runner exists only for the duration of the job
• Designed for reuse across multiple repositories

---

📄 License

MIT License