Shadows Deploy Guardian

Pre-deployment verification checklist — tests, types, build, secrets scan, environment validation. Use before pushing to production or staging.

view source

installs

stars

karma

SkillRank score ↗

8.2/ 10

evaluated by implexa, claude-haiku-4-5 · 2026-05-27

shadows-deploy-guardian enforces a six-gate pre-deployment checklist covering git status, tests, type checking, build validation, secrets scanning, and environment readiness. designed to block deployments when any gate fails.

structure

9.0

trigger phrases

8.0

procedure

9.0

edge cases

7.0

documentation

8.0

strengths

view original SKILL.md from clawhubclick to expand

---
name: deploy-guardian
description: "Pre-deployment verification checklist — tests, types, build, secrets scan, environment validation. Use before pushing to production or staging."
metadata: { "openclaw": { "emoji": "🚀", "homepage": "https://clawhub.ai/NakedoShadow", "requires": { "bins": ["git"], "anyBins": ["npm", "python", "python3", "cargo"] }, "os": ["darwin", "linux", "win32"] } }
---

# Deploy Guardian — Pre-Deployment Verification

**Version**: 1.1.0 | **Author**: Shadows Company | **License**: MIT

---

## WHEN TO TRIGGER

- Before deploying to production or staging
- User says "deploy check", "ready to deploy?", "pre-deploy", "deploy guardian"
- Before creating a release tag
- Before merging a major PR

## WHEN NOT TO TRIGGER

- Local development iterations
- Draft PRs or WIP branches
- Exploratory prototyping with no deployment intent

---

## PREREQUISITES

This skill requires `git` on PATH. Gates 2-4 auto-detect and run only the toolchain present in the project:

| Toolchain | Required for | Detection |
|-----------|-------------|-----------|
| `npm`/`npx` | Node.js projects | `package.json` exists |
| `python`/`python3` | Python projects | `setup.py`, `pyproject.toml`, or `requirements.txt` exists |
| `cargo` | Rust projects | `Cargo.toml` exists |
| `docker` | Containerized builds | `Dockerfile` exists |

The agent MUST check which toolchain is available before running commands. Skip any gate sub-step whose toolchain is absent — do NOT fail the gate for missing optional toolchains.

---

## PROTOCOL — 6 GATES

Each gate must PASS before proceeding. One FAIL = deployment blocked.

### Gate 1 — GIT STATUS

```bash
git status
git log --oneline -5
git remote update --prune 2>/dev/null && git status -uno
```

Verify:
- [ ] Working tree is clean (no uncommitted changes)
- [ ] On the correct branch (main/release/deploy)
- [ ] Branch is up to date with remote (`git rev-parse HEAD` == `git rev-parse @{u}`)
- [ ] No merge conflicts pending

### Gate 2 — TESTS

Detect the project type and run ONLY the matching test runner:

```bash
# Auto-detect: run the FIRST matching runner only
if [ -f package.json ]; then
  npm test 2>&1
elif [ -f pyproject.toml ] || [ -f setup.py ] || [ -f requirements.txt ]; then
  python -m pytest -v 2>&1 || python3 -m pytest -v 2>&1
elif [ -f Cargo.toml ]; then
  cargo test 2>&1
else
  echo "SKIP: No recognized test runner found"
fi
```

Verify:
- [ ] All tests pass (zero failures)
- [ ] No skipped critical tests
- [ ] Exit code is 0

**Note**: This executes project test scripts, which run code from the repository. Only run in trusted repositories or sandboxed environments.

### Gate 3 — TYPE CHECK & LINT

Auto-detect and run ONLY the matching toolchain:

```bash
# TypeScript (if tsconfig.json exists)
[ -f tsconfig.json ] && npx tsc --noEmit 2>&1

# Python (if .py files exist)
[ -f pyproject.toml ] && python -m ruff check . 2>&1

# ESLint (if .eslintrc* exists)
ls .eslintrc* eslint.config.* 2>/dev/null && npx eslint . 2>&1
```

Verify:
- [ ] Zero type errors
- [ ] Zero lint errors (warnings acceptable)
- [ ] SKIP if no type checker / linter is configured (not a failure)

### Gate 4 — BUILD

Auto-detect and run ONLY the matching build system:

```bash
if [ -f package.json ] && grep -q '"build"' package.json; then
  npm run build 2>&1
elif [ -f Dockerfile ]; then
  docker build --dry-run . 2>&1
elif [ -f Cargo.toml ]; then
  cargo build --release 2>&1
else
  echo "SKIP: No build step detected"
fi
```

Verify:
- [ ] Build completes with exit code 0
- [ ] Output artifacts generated in expected location
- [ ] SKIP if no build system detected (not a failure)

**Note**: Build commands execute project scripts. Same sandboxing considerations as Gate 2 apply.

### Gate 5 — SECRETS SCAN

```bash
# Check for leaked secrets in recent commits (last 5)
git diff HEAD~5..HEAD -- . ':!*.lock' ':!*.sum' | grep -inE "(api[_-]?key|secret|token|password|private[_-]?key)\s*[:=]\s*['\"][^'\"]{8,}" || echo "PASS: No secrets pattern detected"

# Check .env files not committed to git
git ls-files | grep -E "\.env$|\.env\.\w+" | head -10

# Check .gitignore has secret patterns
if [ -f .gitignore ]; then
  COVERAGE=$(grep -cE "\.env|secret|credential|\.pem|\.key" .gitignore)
  echo "Gitignore secret coverage: $COVERAGE patterns"
fi
```

Verify:
- [ ] No secrets pattern in recent commits
- [ ] Zero `.env` files tracked by git
- [ ] `.gitignore` covers at least 3 secret patterns
- [ ] No `.pem`, `.key`, `.p12` files tracked

**Limitations**: This grep-based scan catches common patterns but is not a substitute for dedicated secret scanners (gitleaks, trufflehog, detect-secrets). For production environments, consider running a dedicated scanner as an additional step.

**Warning**: Command output may display matched secret-like patterns in the terminal. Run this gate in a secure terminal session where output is not logged to shared systems.

### Gate 6 — ENVIRONMENT VALIDATION

Run concrete automated checks for the target environment:

```bash
# Check required env vars are documented
if [ -f .env.example ]; then
  echo "PASS: .env.example exists ($(wc -l < .env.example) vars documented)"
else
  echo "WARN: No .env.example — required variables not documented"
fi

# Check for pending database migrations (common frameworks)
[ -d migrations ] && ls -1t migrations/ | head -3
[ -d alembic/versions ] && ls -1t alembic/versions/ | head -3

# Check SSL cert validity (if curl available)
if command -v curl &>/dev/null && [ -n "$DEPLOY_URL" ]; then
  curl -sI --max-time 5 "$DEPLOY_URL" | head -5
fi

# Check Docker health (if applicable)
[ -f docker-compose.yml ] && docker compose config --quiet 2>&1 && echo "PASS: docker-compose config valid"
```

Verify:
- [ ] `.env.example` or equivalent documentation exists
- [ ] No unapplied migrations in queue
- [ ] Target URL responds (if `$DEPLOY_URL` is set)
- [ ] Docker config valid (if applicable)
- [ ] SKIP individual checks when not applicable (not a failure)

---

## SECURITY CONSIDERATIONS

1. **Code execution**: Gates 2-4 execute project scripts (`npm test`, `npm run build`, `cargo test`). These commands run arbitrary code from the repository. **Only run this skill on repositories you trust**, or execute within a sandboxed environment (Docker container, CI/CD pipeline, OpenClaw sandbox mode).

2. **Secret exposure**: Gate 5 scans diffs for secret patterns. Matched patterns are displayed in terminal output. Ensure your terminal session is not logged to shared monitoring systems.

3. **Network access**: Gate 6 optionally makes outbound HTTP requests (via `curl`) only if `$DEPLOY_URL` is explicitly set. No other network access is required.

4. **No persistence**: This skill does not modify any configuration files, install packages, store credentials, or make changes outside the terminal session. It is read-only except for the build artifacts produced by Gate 4.

5. **Sandboxing recommendation**: For maximum safety, run deploy-guardian inside a CI/CD pipeline or a sandboxed agent environment rather than directly on a developer workstation.

---

## OUTPUT FORMAT

```markdown
# Deploy Guardian Report
**Date**: [YYYY-MM-DD HH:MM]
**Branch**: [branch name]
**Commit**: [short SHA]
**Target**: [production/staging]
**Toolchain**: [detected: node/python/rust/docker]

## Gate Results

| # | Gate | Status | Details |
|---|------|--------|---------|
| 1 | Git Status | PASS/FAIL | [clean, correct branch, up to date] |
| 2 | Tests | PASS/FAIL/SKIP | [X passed, Y failed, or skipped reason] |
| 3 | Type Check & Lint | PASS/FAIL/SKIP | [errors count or skipped reason] |
| 4 | Build | PASS/FAIL/SKIP | [success or error summary] |
| 5 | Secrets Scan | PASS/FAIL | [patterns found or clean] |
| 6 | Environment | PASS/WARN/SKIP | [checks run and results] |

## Verdict: [CLEAR TO DEPLOY / BLOCKED / CLEAR WITH WARNINGS]

## Blockers (if any)
1. [What needs to be fixed — file:line reference]

## Warnings (if any)
1. [Non-blocking issues to be aware of]

## Recommended Deployment Command
[The actual deploy command to run]
```

---

## RULES

1. **All gates must pass** — no exceptions, no overrides
2. **Secrets gate is non-negotiable** — one leaked secret = full stop
3. **Auto-detect toolchain** — never run commands for absent toolchains
4. **SKIP is not FAIL** — absent toolchains produce SKIP, not FAIL
5. **Test failures block deployment** — even flaky tests must be investigated
6. **Document blockers** — always explain WHY with file:line references
7. **Never auto-deploy** — always wait for explicit user confirmation
8. **Trusted repos only** — warn user if running on an unfamiliar repository

---

**Published by Shadows Company — "We work in the shadows to serve the Light."**

related skills

semantically similar in the cross-vendor index

clawhub

69% match

Release Readiness Checker

Pre-release checklist for shipping software — verify tests pass, changelog updated, version bumped, no debug code, dependencies clean, docs current, no secre...

don't have the plugin yet? install it then click "run inline in claude" again.

restructured original skill into implexa's 6-component format with explicit decision points section, comprehensive inputs/outputs per procedure step, edge case handling (timeouts, network failures, empty results), security warnings expanded, and outcome signals clarified.

Shadows Deploy Guardian

Version: 1.1.0 | Author: nakedoshadow (Shadows Company) | License: MIT

intent

run a 6-gate pre-deployment verification checklist before pushing to production or staging. each gate checks git status, test results, type safety, build output, secret leakage, and environment setup. use when deploying, creating release tags, or merging major PRs. blocks deployment on any failure. auto-detects your project's toolchain (node, python, rust, docker) and runs only relevant checks.

inputs

required

git repository with HEAD pointing to a branch
one of: package.json (node), pyproject.toml/setup.py/requirements.txt (python), Cargo.toml (rust)

external connections / environment

DEPLOY_URL (optional env var): if set, gate 6 validates the target URL responds via HTTP. format: https://example.com
git CLI: must exist on PATH
toolchain CLIs: auto-detected. if absent, gates skip (not fail). requires one of:
- npm/npx (node projects)
- python or python3 (python projects)
- cargo (rust projects)
- docker (if Dockerfile exists)
- curl (optional, for gate 6 URL checks)

context

current working directory is the repo root
user has read access to all files, write access to build output dir only
target deployment environment: production or staging (used in report)

edge cases to handle

network timeout on curl (gate 6): set 5-second max timeout, skip if unreachable
rate limits on secret scanners: grep-based scan has no rate limits but is pattern-matching only
auth expiry: no credentials stored; assume env var access is valid at runtime
empty test results: exit code 0 with zero tests counts as pass
missing build artifacts: fail gate 4 if build succeeds but outputs nothing

procedure

gate 1: git status

run git status and git log --oneline -5. capture working tree state and recent commits.
run git remote update --prune 2>/dev/null && git status -uno. update remote tracking and check for unpushed commits.
inputs: git repo with HEAD. outputs: branch name, commit SHA, dirty/clean status, list of unpushed commits.
verify: working tree clean, branch is main/release/deploy variant, HEAD matches remote, no merge conflict markers in indexed files.

gate 2: tests

check for package.json. if exists, run npm test 2>&1 and capture exit code.
else check for pyproject.toml or setup.py or requirements.txt. if any exist, try python -m pytest -v 2>&1. if fails, retry with python3 -m pytest -v 2>&1.
else check for Cargo.toml. if exists, run cargo test 2>&1.
else echo "SKIP: No recognized test runner found".
inputs: project root, detected toolchain. outputs: test exit code, pass/fail count, skipped test list.
verify: exit code is 0, zero test failures, no critical tests skipped.

gate 3: type check & lint

check if tsconfig.json exists. if yes, run npx tsc --noEmit 2>&1 and capture stderr/stdout.
check if pyproject.toml exists and .py files present. if yes, run python -m ruff check . 2>&1.
check if .eslintrc* or eslint.config.* files exist. if yes, run npx eslint . 2>&1.
if none of above found, output "SKIP: No type checker or linter configured".
inputs: config files, source files. outputs: type error count, lint error count, warning count.
verify: zero type errors, zero lint errors (warnings acceptable), no critical rules disabled.

gate 4: build

check if package.json exists and contains "build" key. if yes, run npm run build 2>&1 and capture exit code.
else check if Dockerfile exists. if yes, run docker build --dry-run . 2>&1.
else check if Cargo.toml exists. if yes, run cargo build --release 2>&1.
else echo "SKIP: No build step detected".
inputs: build config, source files. outputs: build exit code, artifact paths (if generated).
verify: exit code is 0, expected artifacts exist in dist/, build/, target/, or equivalent.

gate 5: secrets scan

run git diff HEAD~5..HEAD -- . ':!*.lock' ':!*.sum'. pipe to grep for secret patterns: (api[_-]?key|secret|token|password|private[_-]?key)\s*[:=]\s*['\"][^'\"]{8,}. if match found, fail. if no match, output "PASS: No secrets pattern detected".
run git ls-files | grep -E "\.env$|\.env\.\w+". if any .env* files are tracked, fail.
check if .gitignore exists. if yes, count secret patterns: grep -cE "\.env|secret|credential|\.pem|\.key" .gitignore. if count < 3, warn. if count >= 3, pass.
check for .pem, .key, .p12 files in git ls-files. if any found, fail.
inputs: last 5 commits, .gitignore, file listing. outputs: pattern matches (if any), tracked secret files (if any), gitignore coverage count.
verify: no secret patterns in diffs, zero .env files tracked, >= 3 secret patterns in .gitignore, zero key files tracked.

gate 6: environment validation

check if .env.example exists. if yes, output "PASS: .env.example exists (N vars documented)" where N is line count. if no, output "WARN: No .env.example".
check if migrations/ directory exists. if yes, list 3 newest files by mtime.
check if alembic/versions/ exists. if yes, list 3 newest files by mtime.
if curl is available AND $DEPLOY_URL env var is set, run curl -sI --max-time 5 "$DEPLOY_URL" | head -5. capture HTTP status code.
check if docker-compose.yml exists. if yes, run docker compose config --quiet 2>&1. if exit code 0, output "PASS: docker-compose config valid". if exit code non-zero, output "FAIL: docker-compose validation failed".
inputs: config files, optional $DEPLOY_URL, optional docker. outputs: env var documentation status, pending migration list, target URL HTTP status, docker config validity.
verify: .env.example or equivalent exists, no unapplied migrations, target URL responds (if $DEPLOY_URL set), docker config valid (if applicable).

decision points

if working tree is dirty (uncommitted changes): fail gate 1. block deployment. recommend git status and git add/commit.

if branch is behind remote: fail gate 1. block deployment. recommend git pull --rebase.

if test runner not found (no package.json, pyproject.toml, setup.py, requirements.txt, Cargo.toml): skip gate 2 (not fail). output "SKIP: No recognized test runner found". continue to gate 3.

if tests fail (exit code non-zero): fail gate 2. block deployment. recommend fixing failing tests before re-running.

if type checker exists but has errors: fail gate 3. block deployment. recommend fixing type errors.

if linter has errors (not warnings): fail gate 3. block deployment. recommend fixing lint errors.

if type checker and linter both absent: skip gate 3 (not fail). output "SKIP: No type checker or linter configured". continue to gate 4.

if build system not detected (no package.json with build, no Dockerfile, no Cargo.toml): skip gate 4 (not fail). output "SKIP: No build step detected". continue to gate 5.

if build fails (exit code non-zero): fail gate 4. block deployment. recommend reviewing build logs.

if secret pattern found in last 5 commits: fail gate 5. block deployment. recommend git log -p HEAD~5..HEAD to review and force-push with secret removed (high risk).

if .env* files tracked by git: fail gate 5. block deployment. recommend git rm --cached .env* and add to .gitignore.

if .gitignore has < 3 secret patterns: warn in gate 6 (not fail). output "WARN: Gitignore secret coverage: N patterns". continue to verdict.

if .pem, .key, or .p12 files tracked: fail gate 5. block deployment. recommend git rm --cached and .gitignore.

if $DEPLOY_URL not set: skip HTTP check in gate 6 (not fail). output "SKIP: DEPLOY_URL not set, skipping URL check". continue to verdict.

if curl to $DEPLOY_URL times out (> 5 seconds): warn in gate 6 (not fail). output "WARN: Target URL unreachable (timeout)". continue to verdict.

if curl returns non-2xx status: warn in gate 6 (not fail). output "WARN: Target URL returned HTTP NNN". continue to verdict.

if docker-compose.yml config invalid: fail gate 6. block deployment. recommend fixing docker-compose syntax.

if .env.example missing: warn in gate 6 (not fail). output "WARN: No .env.example , required variables not documented". continue to verdict.

if any gate fails (not skip, not warn): final verdict is "BLOCKED". do not allow deployment.

if all gates pass (no fails): final verdict is "CLEAR TO DEPLOY".

if all gates pass but one or more warnings (e.g., gitignore coverage, URL timeout, missing .env.example): final verdict is "CLEAR WITH WARNINGS". list warnings and recommend addressing before production.

output contract

generate a markdown report with this structure and save to stdout (and optionally to file deploy-guardian-report.md):

# Deploy Guardian Report
**Date**: [YYYY-MM-DD HH:MM:SS UTC]
**Repository**: [git remote -v origin URL]
**Branch**: [current branch name]
**Commit**: [short SHA, 7 chars]
**Target**: [production/staging, from user input or --target flag]
**Detected Toolchain**: [node/python/rust/docker/multi/unknown]

## Gate Results

| # | Gate | Status | Details |
|---|------|--------|---------|
| 1 | Git Status | PASS/FAIL | [status: clean/dirty, branch: NAME, commits behind: N, merge conflicts: YES/NO] |
| 2 | Tests | PASS/FAIL/SKIP | [M passed, N failed, K skipped; or "SKIP: No test runner"] |
| 3 | Type & Lint | PASS/FAIL/SKIP | [T type errors, L lint errors, W warnings; or "SKIP: No type checker/linter"] |
| 4 | Build | PASS/FAIL/SKIP | [success, artifacts at PATH; or "SKIP: No build detected"] |
| 5 | Secrets Scan | PASS/FAIL | [clean; or "FAIL: N patterns found, M files tracked, K key files"] |
| 6 | Environment | PASS/WARN/SKIP | [.env.example: YES, migrations pending: N, URL: HTTP 200, docker: valid] |

## Verdict
**[CLEAR TO DEPLOY / BLOCKED / CLEAR WITH WARNINGS]**

## Blockers (if any)
1. [Gate N, issue]. file:line references where applicable.
2. [Gate N, issue]. recommended action.

## Warnings (if any)
1. [Non-blocking issue]. recommended action.

## Summary
- Total gates: 6
- Passed: M
- Failed: N
- Skipped: K
- Warnings: W

## Recommended Next Step
[If CLEAR TO DEPLOY: "Run: git push && [deploy command]"]
[If BLOCKED: "Fix blockers above, re-run deploy guardian."]
[If CLEAR WITH WARNINGS: "Address warnings if possible, then: git push && [deploy command]"]

---
*Report generated by Shadows Deploy Guardian v1.1.0*

data format: markdown table for gates, plain text for blockers/warnings. file locations: stdout (always), optional file write to deploy-guardian-report.md in repo root.

exit code: 0 if CLEAR TO DEPLOY, 1 if BLOCKED or has unfixed failures, 2 if CLEAR WITH WARNINGS (optional, configurable).

outcome signal

user sees:

markdown report printed to terminal with green/red status badges or PASS/FAIL text
clear "BLOCKED" or "CLEAR TO DEPLOY" verdict at bottom
explicit list of which gates failed and why
next action: "fix X at file:line and re-run" or "safe to deploy"

user knows it worked if:

all gates show PASS
verdict reads "CLEAR TO DEPLOY"
no blockers listed
exit code is 0 (or 2 if warnings only)
user can now run deployment command with confidence

user knows it failed if:

one or more gates show FAIL
verdict reads "BLOCKED"
blockers section lists specific issues with file:line references
exit code is 1

user knows to investigate if:

verdict reads "CLEAR WITH WARNINGS"
warnings section lists non-blocking issues (e.g., .env.example missing, URL timeout)
user can proceed but should address warnings first

security considerations

code execution: gates 2, 3, 4 execute project scripts (npm test, npm run build, cargo test, npx tsc, python -m pytest). these run arbitrary code from the repo. only run this skill on repos you trust or in a sandboxed environment (docker container, CI/CD pipeline, air-gapped VM).
secret exposure in terminal: gate 5 grep output may display matched secret-like strings. run in a secure terminal session not logged to shared monitoring systems. consider redirecting stdout to a file with restricted perms.
network access: gate 6 makes outbound HTTP requests only if $DEPLOY_URL is explicitly set. no other network access. curl requests have 5-second timeout to prevent hanging.
no persistence: this skill is read-only except for build artifacts (gate 4). does not modify .env files, install packages, store credentials, or change git state.
sandboxing strongly recommended: for production deployments, run deploy-guardian inside a CI/CD pipeline (GitHub Actions, GitLab CI, Jenkins) or isolated agent environment rather than on a developer laptop. this limits exposure to malicious repository code and logs output securely.
grep-based secrets scan limitation: pattern matching via grep catches common leaks but is not a substitute for dedicated secret scanners (gitleaks, trufflehog, detect-secrets). for high-security environments, integrate one of those tools as an additional gate.

Published by nakedoshadow (Shadows Company) , "We work in the shadows to serve the Light."