# 🎪 Superset Showtime
**Modern ephemeral environment management for Apache Superset using circus tent emoji labels**
[](https://badge.fury.io/py/superset-showtime)
[](https://www.python.org/downloads/)
## 🎯 What is Showtime?
Superset Showtime is a CLI tool designed primarily for **GitHub Actions** to manage Apache Superset ephemeral environments. It uses **circus tent emoji labels** as a visual state management system and depends on Superset's existing build infrastructure.
## 🚀 Quick Start for Superset Contributors
**Create an ephemeral environment:**
1. Go to your PR in GitHub
2. Add label: `🎪 ⚡ showtime-trigger-start`
3. Watch the magic happen - labels will update automatically
4. When you see `🎪 🚦 {sha} running`, your environment is ready!
5. Get URL from `🎪 🌐 {sha} {ip}` → `http://{ip}:8080`
6. **Every new commit automatically deploys a fresh environment** (zero-downtime)
**To test a specific commit without auto-updates:**
- Add label: `🎪 🧊 showtime-freeze` (prevents auto-sync on new commits)
**Clean up when done:**
```bash
# Add this label:
🎪 🛑 showtime-trigger-stop
# All circus labels disappear, AWS resources cleaned up
```
## 🎪 How It Works
**🎪 GitHub labels become a visual state machine:**
```bash
# User adds trigger label in GitHub UI:
🎪 ⚡ showtime-trigger-start
# System responds with state labels:
🎪 abc123f 🚦 building # Environment abc123f is building
🎪 🎯 abc123f # abc123f is the active environment
🎪 abc123f 📅 2024-01-15T14-30 # Created timestamp
🎪 abc123f ⌛ 24h # Time-to-live policy
🎪 abc123f 🤡 maxime # Requested by maxime (clown emoji!)
# When ready:
🎪 abc123f 🚦 running # Environment is now running
🎪 abc123f 🌐 52-1-2-3 # Available at http://52.1.2.3:8080
```
### 🔄 Showtime Workflow
```mermaid
flowchart TD
A[User adds 🎪 ⚡ trigger-start] --> B[GitHub Actions: sync]
B --> C{Current state?}
C -->|No environment| D[🔒 Claim: Remove trigger + Set building]
C -->|Running + new SHA| E[🔒 Claim: Remove trigger + Set building]
C -->|Already building| F[❌ Exit: Another job active]
C -->|No triggers| G[❌ Exit: Nothing to do]
D --> H[📋 State: building]
E --> H
H --> I[🐳 Docker build]
I -->|Success| J[📋 State: built]
I -->|Fail| K[📋 State: failed]
J --> L[📋 State: deploying]
L --> M[☁️ AWS Deploy]
M -->|Success| N[📋 State: running]
M -->|Fail| O[📋 State: failed]
N --> P[🎪 Environment ready!]
Q[User adds 🎪 🛑 trigger-stop] --> R[🧹 Cleanup AWS + Remove labels]
```
**Install CLI for debugging:**
```bash
pip install superset-showtime
export GITHUB_TOKEN=your_token
```
**Monitor and debug:**
```bash
showtime list # See all active environments
showtime status 1234 # Debug specific environment
showtime labels # Complete label reference
```
**Testing/development:**
```bash
showtime sync 1234 --dry-run-aws --dry-run-docker # Test without costs
showtime cleanup --dry-run --older-than 1h # Test cleanup logic
```
> **Architecture**: This CLI implements ACID-style atomic transactions with direct Docker integration. It handles complete environment lifecycle from Docker build to AWS deployment with race condition prevention.
## 🎪 Complete Label Reference
### 🎯 Trigger Labels (Add These to Your PR)
| Label | Action | Result |
|-------|---------|---------|
| `🎪 ⚡ showtime-trigger-start` | Create environment | Builds and deploys ephemeral environment with blue-green deployment |
| `🎪 🛑 showtime-trigger-stop` | Destroy environment | Cleans up AWS resources and removes all labels |
| `🎪 🧊 showtime-freeze` | Freeze environment | Prevents auto-sync on new commits (for testing specific SHAs) |
### 📊 State Labels (Automatically Managed)
| Label Pattern | Meaning | Example |
|---------------|---------|---------|
| `🎪 {sha} 🚦 {status}` | Environment status | `🎪 abc123f 🚦 running` |
| `🎪 🎯 {sha}` | Active environment pointer | `🎪 🎯 abc123f` |
| `🎪 🏗️ {sha}` | Building environment pointer | `🎪 🏗️ def456a` |
| `🎪 {sha} 📅 {timestamp}` | Creation time | `🎪 abc123f 📅 2024-01-15T14-30` |
| `🎪 {sha} 🌐 {ip:port}` | Environment URL | `🎪 abc123f 🌐 52.1.2.3:8080` |
| `🎪 {sha} ⌛ {ttl}` | Time-to-live policy | `🎪 abc123f ⌛ 24h` |
| `🎪 {sha} 🤡 {username}` | Who requested | `🎪 abc123f 🤡 maxime` |
## 🔧 Testing Configuration Changes
**Approach**: Modify configuration directly in your PR code, then trigger environment.
**Workflow**:
1. Modify `superset_config.py` with your changes
2. Push commit → Creates new SHA (e.g., `def456a`)
3. Add `🎪 ⚡ showtime-trigger-start` → Deploys with your config
4. Test environment reflects your exact code changes
This approach creates traceable, reviewable changes that are part of your git history.
## 🔄 Complete Workflows
### Creating Your First Environment
1. **Add trigger label** in GitHub UI: `🎪 ⚡ showtime-trigger-start`
2. **Watch state labels appear:**
```
🎪 abc123f 🚦 building ← Environment is building
🎪 🎯 abc123f ← This is the active environment
🎪 abc123f 📅 2024-01-15T14-30 ← Started building at this time
```
3. **Wait for completion:**
```
🎪 abc123f 🚦 running ← Now ready!
🎪 abc123f 🌐 52.1.2.3:8080 ← Visit http://52.1.2.3:8080
```
### Testing Specific Commits
1. **Add freeze label:** `🎪 🧊 showtime-freeze`
2. **Result:** Environment won't auto-update on new commits
3. **Use case:** Test specific SHA while continuing development
4. **Override:** Add `🎪 ⚡ showtime-trigger-start` to force update despite freeze
### Rolling Updates (Automatic!)
When you push new commits, Showtime automatically:
1. **Detects new commit** via GitHub webhook
2. **Builds new environment** alongside old one
3. **Switches traffic** when new environment is ready
4. **Cleans up old environment**
You'll see:
```bash
# During update:
🎪 abc123f 🚦 running # Old environment still serving
🎪 def456a 🚦 building # New environment building
🎪 🎯 abc123f # Traffic still on old
🎪 🏗️ def456a # New one being prepared
# After update:
🎪 def456a 🚦 running # New environment live
🎪 🎯 def456a # Traffic switched
🎪 def456a 🌐 52-4-5-6 # New IP address
# All abc123f labels removed automatically
```
## 🔒 Security & Permissions
### Who Can Use This?
- **✅ Superset maintainers** (with write access) can add trigger labels
- **❌ External contributors** cannot trigger environments (no write access to add labels)
- **🔒 Secure by design** - only trusted users can create expensive AWS resources
### GitHub Actions Integration
**🎯 Live Workflow**: [showtime-trigger.yml](https://github.com/apache/superset/actions/workflows/showtime-trigger.yml)
**How it works:**
- Triggers on PR label changes, commits, and closures
- Installs `superset-showtime` from PyPI (trusted code, not PR code)
- Runs `showtime sync` to handle trigger processing and deployments
- Supports manual testing via `workflow_dispatch` with specific SHA override
**Commands used:**
```bash
showtime sync PR_NUMBER --check-only # Determine build_needed + target_sha
showtime sync PR_NUMBER --sha SHA # Execute atomic claim + build + deploy
```
## 🛠️ CLI Usage
The CLI is primarily used by GitHub Actions, but available for debugging and advanced users:
```bash
pip install superset-showtime
export GITHUB_TOKEN=your_token
# Core commands:
showtime sync PR_NUMBER # Sync to desired state (main command)
showtime start PR_NUMBER # Create new environment
showtime stop PR_NUMBER # Delete environment
showtime status PR_NUMBER # Show current state
showtime list # List all environments
showtime cleanup --older-than 48h # Clean up expired environments
```
## 🤝 Contributing
### Testing Your Changes
**Test with real PRs safely:**
```bash
# Test full workflow without costs:
showtime sync YOUR_PR_NUMBER --dry-run-aws --dry-run-docker
# Test cleanup logic:
showtime cleanup --dry-run --older-than 24h
```
### Development Setup
```bash
git clone https://github.com/mistercrunch/superset-showtime
cd superset-showtime
# Using uv (recommended):
uv pip install -e ".[dev]"
make pre-commit
make test
# Traditional pip:
pip install -e ".[dev]"
pre-commit install
pytest
```
## 📄 License
Apache License 2.0 - same as Apache Superset.
---
**🎪 "Ladies and gentlemen, welcome to Superset Showtime - where ephemeral environments are always under the big top!"** 🎪🤡✨
Raw data
{
"_id": null,
"home_page": null,
"name": "superset-showtime",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "aws, circus, devops, environments, ephemeral, github, showtime, superset",
"author": null,
"author_email": "Maxime Beauchemin <maximebeauchemin@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/45/54/eff5ad2b5a4302eddcebd40e1cc38946c42bd535029a98d667de2ed9d544/superset_showtime-0.5.12.tar.gz",
"platform": null,
"description": "# \ud83c\udfaa Superset Showtime\n\n**Modern ephemeral environment management for Apache Superset using circus tent emoji labels**\n\n[](https://badge.fury.io/py/superset-showtime)\n[](https://www.python.org/downloads/)\n\n## \ud83c\udfaf What is Showtime?\n\nSuperset Showtime is a CLI tool designed primarily for **GitHub Actions** to manage Apache Superset ephemeral environments. It uses **circus tent emoji labels** as a visual state management system and depends on Superset's existing build infrastructure.\n\n## \ud83d\ude80 Quick Start for Superset Contributors\n\n**Create an ephemeral environment:**\n1. Go to your PR in GitHub\n2. Add label: `\ud83c\udfaa \u26a1 showtime-trigger-start`\n3. Watch the magic happen - labels will update automatically\n4. When you see `\ud83c\udfaa \ud83d\udea6 {sha} running`, your environment is ready!\n5. Get URL from `\ud83c\udfaa \ud83c\udf10 {sha} {ip}` \u2192 `http://{ip}:8080`\n6. **Every new commit automatically deploys a fresh environment** (zero-downtime)\n\n**To test a specific commit without auto-updates:**\n- Add label: `\ud83c\udfaa \ud83e\uddca showtime-freeze` (prevents auto-sync on new commits)\n\n**Clean up when done:**\n```bash\n# Add this label:\n\ud83c\udfaa \ud83d\uded1 showtime-trigger-stop\n# All circus labels disappear, AWS resources cleaned up\n```\n\n## \ud83c\udfaa How It Works\n\n**\ud83c\udfaa GitHub labels become a visual state machine:**\n```bash\n# User adds trigger label in GitHub UI:\n\ud83c\udfaa \u26a1 showtime-trigger-start\n\n# System responds with state labels:\n\ud83c\udfaa abc123f \ud83d\udea6 building # Environment abc123f is building\n\ud83c\udfaa \ud83c\udfaf abc123f # abc123f is the active environment\n\ud83c\udfaa abc123f \ud83d\udcc5 2024-01-15T14-30 # Created timestamp\n\ud83c\udfaa abc123f \u231b 24h # Time-to-live policy\n\ud83c\udfaa abc123f \ud83e\udd21 maxime # Requested by maxime (clown emoji!)\n\n# When ready:\n\ud83c\udfaa abc123f \ud83d\udea6 running # Environment is now running\n\ud83c\udfaa abc123f \ud83c\udf10 52-1-2-3 # Available at http://52.1.2.3:8080\n```\n\n### \ud83d\udd04 Showtime Workflow\n\n```mermaid\nflowchart TD\n A[User adds \ud83c\udfaa \u26a1 trigger-start] --> B[GitHub Actions: sync]\n B --> C{Current state?}\n\n C -->|No environment| D[\ud83d\udd12 Claim: Remove trigger + Set building]\n C -->|Running + new SHA| E[\ud83d\udd12 Claim: Remove trigger + Set building]\n C -->|Already building| F[\u274c Exit: Another job active]\n C -->|No triggers| G[\u274c Exit: Nothing to do]\n\n D --> H[\ud83d\udccb State: building]\n E --> H\n H --> I[\ud83d\udc33 Docker build]\n I -->|Success| J[\ud83d\udccb State: built]\n I -->|Fail| K[\ud83d\udccb State: failed]\n\n J --> L[\ud83d\udccb State: deploying]\n L --> M[\u2601\ufe0f AWS Deploy]\n M -->|Success| N[\ud83d\udccb State: running]\n M -->|Fail| O[\ud83d\udccb State: failed]\n\n N --> P[\ud83c\udfaa Environment ready!]\n\n Q[User adds \ud83c\udfaa \ud83d\uded1 trigger-stop] --> R[\ud83e\uddf9 Cleanup AWS + Remove labels]\n```\n\n\n**Install CLI for debugging:**\n```bash\npip install superset-showtime\nexport GITHUB_TOKEN=your_token\n```\n\n**Monitor and debug:**\n```bash\nshowtime list # See all active environments\nshowtime status 1234 # Debug specific environment\nshowtime labels # Complete label reference\n```\n\n**Testing/development:**\n```bash\nshowtime sync 1234 --dry-run-aws --dry-run-docker # Test without costs\nshowtime cleanup --dry-run --older-than 1h # Test cleanup logic\n```\n\n> **Architecture**: This CLI implements ACID-style atomic transactions with direct Docker integration. It handles complete environment lifecycle from Docker build to AWS deployment with race condition prevention.\n\n## \ud83c\udfaa Complete Label Reference\n\n### \ud83c\udfaf Trigger Labels (Add These to Your PR)\n\n| Label | Action | Result |\n|-------|---------|---------|\n| `\ud83c\udfaa \u26a1 showtime-trigger-start` | Create environment | Builds and deploys ephemeral environment with blue-green deployment |\n| `\ud83c\udfaa \ud83d\uded1 showtime-trigger-stop` | Destroy environment | Cleans up AWS resources and removes all labels |\n| `\ud83c\udfaa \ud83e\uddca showtime-freeze` | Freeze environment | Prevents auto-sync on new commits (for testing specific SHAs) |\n\n### \ud83d\udcca State Labels (Automatically Managed)\n\n| Label Pattern | Meaning | Example |\n|---------------|---------|---------|\n| `\ud83c\udfaa {sha} \ud83d\udea6 {status}` | Environment status | `\ud83c\udfaa abc123f \ud83d\udea6 running` |\n| `\ud83c\udfaa \ud83c\udfaf {sha}` | Active environment pointer | `\ud83c\udfaa \ud83c\udfaf abc123f` |\n| `\ud83c\udfaa \ud83c\udfd7\ufe0f {sha}` | Building environment pointer | `\ud83c\udfaa \ud83c\udfd7\ufe0f def456a` |\n| `\ud83c\udfaa {sha} \ud83d\udcc5 {timestamp}` | Creation time | `\ud83c\udfaa abc123f \ud83d\udcc5 2024-01-15T14-30` |\n| `\ud83c\udfaa {sha} \ud83c\udf10 {ip:port}` | Environment URL | `\ud83c\udfaa abc123f \ud83c\udf10 52.1.2.3:8080` |\n| `\ud83c\udfaa {sha} \u231b {ttl}` | Time-to-live policy | `\ud83c\udfaa abc123f \u231b 24h` |\n| `\ud83c\udfaa {sha} \ud83e\udd21 {username}` | Who requested | `\ud83c\udfaa abc123f \ud83e\udd21 maxime` |\n\n## \ud83d\udd27 Testing Configuration Changes\n\n**Approach**: Modify configuration directly in your PR code, then trigger environment.\n\n**Workflow**:\n1. Modify `superset_config.py` with your changes\n2. Push commit \u2192 Creates new SHA (e.g., `def456a`)\n3. Add `\ud83c\udfaa \u26a1 showtime-trigger-start` \u2192 Deploys with your config\n4. Test environment reflects your exact code changes\n\nThis approach creates traceable, reviewable changes that are part of your git history.\n\n## \ud83d\udd04 Complete Workflows\n\n### Creating Your First Environment\n\n1. **Add trigger label** in GitHub UI: `\ud83c\udfaa \u26a1 showtime-trigger-start`\n2. **Watch state labels appear:**\n ```\n \ud83c\udfaa abc123f \ud83d\udea6 building \u2190 Environment is building\n \ud83c\udfaa \ud83c\udfaf abc123f \u2190 This is the active environment\n \ud83c\udfaa abc123f \ud83d\udcc5 2024-01-15T14-30 \u2190 Started building at this time\n ```\n3. **Wait for completion:**\n ```\n \ud83c\udfaa abc123f \ud83d\udea6 running \u2190 Now ready!\n \ud83c\udfaa abc123f \ud83c\udf10 52.1.2.3:8080 \u2190 Visit http://52.1.2.3:8080\n ```\n\n### Testing Specific Commits\n\n1. **Add freeze label:** `\ud83c\udfaa \ud83e\uddca showtime-freeze`\n2. **Result:** Environment won't auto-update on new commits\n3. **Use case:** Test specific SHA while continuing development\n4. **Override:** Add `\ud83c\udfaa \u26a1 showtime-trigger-start` to force update despite freeze\n\n### Rolling Updates (Automatic!)\n\nWhen you push new commits, Showtime automatically:\n1. **Detects new commit** via GitHub webhook\n2. **Builds new environment** alongside old one\n3. **Switches traffic** when new environment is ready\n4. **Cleans up old environment**\n\nYou'll see:\n```bash\n# During update:\n\ud83c\udfaa abc123f \ud83d\udea6 running # Old environment still serving\n\ud83c\udfaa def456a \ud83d\udea6 building # New environment building\n\ud83c\udfaa \ud83c\udfaf abc123f # Traffic still on old\n\ud83c\udfaa \ud83c\udfd7\ufe0f def456a # New one being prepared\n\n# After update:\n\ud83c\udfaa def456a \ud83d\udea6 running # New environment live\n\ud83c\udfaa \ud83c\udfaf def456a # Traffic switched\n\ud83c\udfaa def456a \ud83c\udf10 52-4-5-6 # New IP address\n# All abc123f labels removed automatically\n```\n\n## \ud83d\udd12 Security & Permissions\n\n### Who Can Use This?\n\n- **\u2705 Superset maintainers** (with write access) can add trigger labels\n- **\u274c External contributors** cannot trigger environments (no write access to add labels)\n- **\ud83d\udd12 Secure by design** - only trusted users can create expensive AWS resources\n\n### GitHub Actions Integration\n\n**\ud83c\udfaf Live Workflow**: [showtime-trigger.yml](https://github.com/apache/superset/actions/workflows/showtime-trigger.yml)\n\n**How it works:**\n- Triggers on PR label changes, commits, and closures\n- Installs `superset-showtime` from PyPI (trusted code, not PR code)\n- Runs `showtime sync` to handle trigger processing and deployments\n- Supports manual testing via `workflow_dispatch` with specific SHA override\n\n**Commands used:**\n```bash\nshowtime sync PR_NUMBER --check-only # Determine build_needed + target_sha\nshowtime sync PR_NUMBER --sha SHA # Execute atomic claim + build + deploy\n```\n\n## \ud83d\udee0\ufe0f CLI Usage\n\nThe CLI is primarily used by GitHub Actions, but available for debugging and advanced users:\n\n```bash\npip install superset-showtime\nexport GITHUB_TOKEN=your_token\n\n# Core commands:\nshowtime sync PR_NUMBER # Sync to desired state (main command)\nshowtime start PR_NUMBER # Create new environment\nshowtime stop PR_NUMBER # Delete environment\nshowtime status PR_NUMBER # Show current state\nshowtime list # List all environments\nshowtime cleanup --older-than 48h # Clean up expired environments\n```\n\n\n\n## \ud83e\udd1d Contributing\n\n### Testing Your Changes\n\n**Test with real PRs safely:**\n```bash\n# Test full workflow without costs:\nshowtime sync YOUR_PR_NUMBER --dry-run-aws --dry-run-docker\n\n# Test cleanup logic:\nshowtime cleanup --dry-run --older-than 24h\n```\n\n### Development Setup\n\n```bash\ngit clone https://github.com/mistercrunch/superset-showtime\ncd superset-showtime\n\n# Using uv (recommended):\nuv pip install -e \".[dev]\"\nmake pre-commit\nmake test\n\n# Traditional pip:\npip install -e \".[dev]\"\npre-commit install\npytest\n```\n\n## \ud83d\udcc4 License\n\nApache License 2.0 - same as Apache Superset.\n\n---\n\n**\ud83c\udfaa \"Ladies and gentlemen, welcome to Superset Showtime - where ephemeral environments are always under the big top!\"** \ud83c\udfaa\ud83e\udd21\u2728\n",
"bugtrack_url": null,
"license": null,
"summary": "\ud83c\udfaa Apache Superset ephemeral environment management with circus tent emoji state tracking",
"version": "0.5.12",
"project_urls": {
"Bug Tracker": "https://github.com/apache/superset-showtime/issues",
"Changelog": "https://github.com/apache/superset-showtime/blob/main/CHANGELOG.md",
"Documentation": "https://superset-showtime.readthedocs.io/",
"Homepage": "https://github.com/apache/superset-showtime",
"Repository": "https://github.com/apache/superset-showtime.git"
},
"split_keywords": [
"aws",
" circus",
" devops",
" environments",
" ephemeral",
" github",
" showtime",
" superset"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cbb183fd510d6f0980b05340920b7795aa226fd817aa718c748d5fe3e7f4eed9",
"md5": "30192d8a64d7d9fe18dc1839ef930ef1",
"sha256": "d65d9342e5d174d94676e6b87168015215e91333e6f828234f67b8bfcac22527"
},
"downloads": -1,
"filename": "superset_showtime-0.5.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "30192d8a64d7d9fe18dc1839ef930ef1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 42302,
"upload_time": "2025-08-26T00:49:35",
"upload_time_iso_8601": "2025-08-26T00:49:35.177269Z",
"url": "https://files.pythonhosted.org/packages/cb/b1/83fd510d6f0980b05340920b7795aa226fd817aa718c748d5fe3e7f4eed9/superset_showtime-0.5.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4554eff5ad2b5a4302eddcebd40e1cc38946c42bd535029a98d667de2ed9d544",
"md5": "45225885be4115244faed13dcb8c9b08",
"sha256": "60eeb1290fdb781a07778262ede6ebad57bde21d9d7358089b3d836979f6afdc"
},
"downloads": -1,
"filename": "superset_showtime-0.5.12.tar.gz",
"has_sig": false,
"md5_digest": "45225885be4115244faed13dcb8c9b08",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 53290,
"upload_time": "2025-08-26T00:49:36",
"upload_time_iso_8601": "2025-08-26T00:49:36.539499Z",
"url": "https://files.pythonhosted.org/packages/45/54/eff5ad2b5a4302eddcebd40e1cc38946c42bd535029a98d667de2ed9d544/superset_showtime-0.5.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 00:49:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "apache",
"github_project": "superset-showtime",
"github_not_found": true,
"lcname": "superset-showtime"
}
JSON
