One command. Complete, production-grade GitHub Actions pipeline instantly scaffolded into any Node.js, Java, or Python project.
monolithx is an interactive CLI that writes a full CI/CD pipeline into your repository. Run it once, answer a few prompts, push — and every future commit is automatically linted, tested, built, scanned, deployed to staging, and promoted to production through an approval gate, with instant rollback at any time.
Every push / PR
│
▼
┌─────────────┐
│ CI │ lint + test (setup-node / setup-java / setup-python + dep cache)
└──────┬──────┘
│ success on prod/staging branch
▼
┌─────────────┐
│ Build │ docker build → push to GHCR (immutable SHA tag)
│ │ Trivy image scan (blocks on CRITICAL/HIGH CVEs)
└──────┬──────┘
│
├──────────────────────────────────────────────────────────┐
│ head_branch == staging │ head_branch == main
▼ ▼
┌─────────────┐ ┌──────────────────────┐
│ Deploy │ │ Deploy │
│ Staging │ auto (GitHub Environment: staging) │ Production │
│ │ SSH → docker pull exact SHA → run │ ← manual approval │
│ │ health check → auto-rollback on fail │ (GitHub Environment)│
└─────────────┘ └──────────────────────┘
Manual at any time:
workflow_dispatch → Rollback workflow → specify any SHA → SSH → redeploy → health check
workflow_dispatch → Security Scan → Trivy FS + Gitleaks (also runs weekly)
# Install globally
npm install -g monolithx
# Run inside your project root
cd my-project
monolithxThe CLI will prompt you for:
| Prompt | Default | Notes |
|---|---|---|
| Project name | folder name | Used as container name and image name |
| Stack | — | Node.js, Java, Python |
| Production branch | main |
Auto-deploys here after approval |
| Staging branch | staging |
Auto-deploys here on every push |
| Install command | preset | e.g. npm ci |
| Lint command | preset | e.g. npm run lint --if-present |
| Test command | preset | e.g. npm test |
| Use Docker? | yes | Recommended for production |
| Migration command | empty | Optional; run before container swap |
.github/
workflows/
ci.yml ← lint + test on every push / PR
build.yml ← Docker build → GHCR push + Trivy scan
deploy.yml ← staging (auto) / production (approval gate)
rollback.yml ← manual rollback to any image SHA
security-scan.yml ← weekly Trivy FS + Gitleaks secret scan
scripts/
deploy.sh ← runs on server via SSH: pull exact image, restart
rollback.sh ← runs on server via SSH: restore previous or explicit SHA
health-check.sh ← polls health endpoint until 2xx or timeout
Dockerfile ← multi-stage, non-root user, HEALTHCHECK
.dockerignore ← excludes .git, secrets, node_modules, etc.
| Secret | Description |
|---|---|
PROD_HOST |
Production server IP or hostname |
STAGING_HOST |
Staging server IP or hostname |
DEPLOY_USER |
SSH username on both servers |
DEPLOY_SSH_KEY |
Private SSH key (ed25519 recommended) |
GITHUB_TOKENis used automatically for GHCR login and SARIF uploads — no manual setup needed.
| Environment | Recommended settings |
|---|---|
staging |
No protection rules (fully automatic) |
production |
Add required reviewers → creates an approval gate before every production deploy |
# Create directories
mkdir -p /opt/scripts/<your-app-name>
mkdir -p /etc/<your-app-name>
# Copy scripts from your repo to the server
scp scripts/deploy.sh user@server:/opt/scripts/<app>/deploy.sh
scp scripts/rollback.sh user@server:/opt/scripts/<app>/rollback.sh
chmod +x /opt/scripts/<app>/*.sh
# Place environment files (never commit these)
# /etc/<app>/staging.env
# /etc/<app>/production.env
# Add the GitHub Actions SSH public key to authorized_keys
echo "<public-key>" >> ~/.ssh/authorized_keys
# Ensure Docker is installed and the deploy user can run DockerRollback is a workflow_dispatch — go to Actions → Rollback → Run workflow.
- Enter the exact image SHA you want to roll back to (visible in the Build & Push job log).
- Select the target environment (
stagingorproduction). - The workflow SSHes into the server,
docker pulls the exact immutable image, swaps the container, and verifies health.
The deploy.sh script also records the running image tag before each deploy, enabling IMAGE_TAG=previous rollback without needing to look up a SHA.
- GHCR images are tagged with the full commit SHA (immutable) —
latestis never deployed to production. - Trivy scans every built image for CRITICAL and HIGH CVEs before the deploy step can run. Results appear in the GitHub Security tab.
- Gitleaks scans the full git history for accidentally committed secrets on every push to main/staging.
- Secrets are injected at runtime via
--env-fileon the server — never baked into the image. - Non-root users in all three Dockerfile templates.
- Supply chain: pinned major versions on all Actions (
@v4,@v3, etc.).
| Stack | Runtime | Install | Lint | Test | Server |
|---|---|---|---|---|---|
| Node.js | Node 20 | npm ci |
npm run lint |
npm test |
npm start |
| Java | JDK 21 (Temurin) | mvn dependency:go-offline |
Checkstyle | mvn verify |
JVM container flags |
| Python | Python 3.11 | pip install -r requirements.txt |
ruff / flake8 | pytest |
gunicorn + uvicorn |
Q: Where does the Docker image actually run?
A: On your own server (VPS, EC2, Droplet, etc.). The GitHub Actions runner builds and pushes the image to GHCR, then SSHes into your server to pull and start it. The runner itself is ephemeral.
Q: Can I use this with Kubernetes?
A: The deploy.sh and rollback.sh scripts are the only server-side concern. Replace their contents with kubectl set image / kubectl rollout undo commands to target a Kubernetes cluster instead.
Q: What if I don't want Docker?
A: Answer "No" to the Docker prompt. The build step uploads a plain artifact (dist/) instead, and you'll need to adapt deploy.sh to copy and run that artifact on your server.
Q: How do I update the pipeline after initial setup?
A: Re-run monolithx — it overwrites the generated files. Commit the changes and push.
MIT