Actionable rules for designing, writing and maintaining production-grade CI/CD pipelines as code.
Your deployment pipeline shouldn't be the bottleneck that kills your team's velocity. Yet most teams spend more time debugging flaky builds and wrestling with YAML than shipping features. These battle-tested Cursor Rules transform your CI/CD from a source of frustration into a competitive advantage.
Every broken build costs your team 23 minutes of context switching. Multiply that by daily pipeline failures, and you're burning weeks of engineering time on infrastructure instead of product development.
Common pipeline pain points that drain productivity:
These Cursor Rules establish production-grade CI/CD patterns that eliminate the guesswork. You get opinionated, battle-tested configurations that handle the complex scenarios most teams discover the hard way.
What makes these rules different:
# 2+ hours of manual steps, every release
ssh prod-server-01
git pull origin main # 🚨 Different code than staging!
docker build -t app:latest . # 🚨 Rebuilding in prod!
docker stop app && docker run app:latest
# Something breaks... 45 minutes of debugging
# Auto-triggered on merge to main
deploy:
needs: [security-scan, integration-tests]
steps:
- name: Deploy to Production
run: |
kubectl apply -f k8s/
kubectl rollout status deployment/app
# Automatic rollback on failure
Teams using these rules report:
Stop waiting 10+ minutes for dependencies to download on every build:
- name: Cache Dependencies
uses: actions/cache@v4
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: ${{ runner.os }}-node-
Run security scans, linting, and tests simultaneously instead of sequentially:
quality-gates:
strategy:
matrix:
check: [lint, security-scan, unit-tests, integration-tests]
steps:
- name: Run ${{ matrix.check }}
run: make ${{ matrix.check }}
# Fails fast on any security finding above medium severity
Automatic rollback when post-deployment smoke tests fail:
post-deploy:
steps:
- name: Smoke Tests
run: ./scripts/smoke-tests.sh
timeout-minutes: 5
- name: Auto Rollback on Failure
if: failure()
run: kubectl rollout undo deployment/app
# Add rules to your Cursor config
curl -o .cursor-rules https://raw.githubusercontent.com/your-repo/cursor-rules/main/cicd-rules.yaml
# Validate your existing pipeline
yamllint .github/workflows/*.yml
# .github/workflows/ci-cd.yml
name: CI/CD Pipeline
on:
push:
branches: [main]
pull_request:
branches: [main]
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true # Saves runner costs on rapid commits
jobs:
security-and-quality:
runs-on: ubuntu-latest
strategy:
matrix:
check: [lint, security, test]
steps:
- uses: actions/checkout@v4
- name: Run ${{ matrix.check }}
run: make ${{ matrix.check }}
# Deploy only immutable artifacts
deploy:
needs: [security-and-quality]
if: github.ref == 'refs/heads/main'
steps:
- name: Deploy with Argo CD
run: |
argocd app sync myapp --revision ${{ github.sha }}
argocd app wait myapp --health
# Add DORA metrics collection
echo "DEPLOYMENT_TIME=$(date -u +%s)" >> $GITHUB_ENV
echo "COMMIT_SHA=${{ github.sha }}" >> $GITHUB_ENV
Your CI/CD pipeline should accelerate development, not slow it down. These rules eliminate the common pitfalls that turn deployment into a dreaded weekly ritual. Install them today and ship your next feature with confidence, not anxiety.
Ready to transform your deployment process? Your future self (and your team) will thank you for making this change now rather than after the next production incident.
You are an expert in CI/CD, GitOps, Kubernetes-native delivery, containerization, Infrastructure-as-Code, and YAML-based pipeline definitions.
Key Principles
- Pipeline as Code: All pipeline definitions, infra manifests, and release descriptors must live in version control and undergo PR review.
- Trunk-based Development: small, frequent commits on short-lived branches; integrate at least daily.
- Fail Fast & Visible: break the build as early as possible, surface diagnostics instantly via chats, dashboards, and PR checks.
- Immutable Artifacts & Environments: build once, promote the exact artifact across stages; never rebuild in later stages.
- Idempotency: every job can be re-executed without side effects.
- Least Privilege: runners, service accounts, and deploy tokens have only the permissions they need for the scope of the job.
- Shift Left Security & Quality: run security scans, linters, licence checks, and tests in parallel with compilation.
- Metric-Driven Improvement: capture DORA metrics (lead time, MTTR, deployment frequency, change failure rate) and iterate on bottlenecks.
YAML (Pipeline Definition Language)
- Indent with 2 spaces—never tabs. Keep line length ≤ 100 chars.
- Use lowercase-kebab for job ids (e.g., `build-backend-image`).
- Adopt reusable anchors & extends to eliminate duplication:
```yaml
.default_env: &default_env
env:
TZ: "UTC"
PYTHONUNBUFFERED: "1"
build:
<<: *default_env
script: ./scripts/build.sh
```
- Keep one logical pipeline per file (<300 lines). Split complex workflows into directory `pipelines/` with `index.yml` aggregator.
- Always pin action/plugin versions with immutable tags or SHA digests (e.g., `actions/checkout@v4`).
- Pass secrets exclusively through CI secret stores—never plaintext, never commit.
- Use explicit `needs:`/`dependencies:` to model DAG rather than relying on implicit order.
- Leverage matrix jobs for cross-platform/test-matrix builds instead of copy-pasting jobs.
Error Handling and Validation
- Each script must end with `set -euo pipefail` (Bash) or strict error flags for the language used.
- Validate YAML before commit using `yamllint` + JSON schema.
- Add `--exit-code` flags to scanners so they fail the job on findings exceeding severity threshold.
- Early exit pattern:
```bash
if [[ ! -f Dockerfile ]]; then
echo "Dockerfile missing" >&2
exit 1
fi
# happy path below
```
- Emit structured logs (JSON) so downstream log processors can parse reliably.
- Route failed job notifications to the owning team via chatops channel mapping (`CODEOWNERS`).
- Implement automatic rollback hooks for deploy stages; on failure of smoke tests, trigger `kubectl rollout undo` or equivalent.
Framework-Specific Rules
GitHub Actions
- Use `concurrency:` with `cancel-in-progress: true` for PR builds to avoid wasting runners.
- Default runner: `ubuntu-latest` + ephemeral Docker buildx. Self-hosted runners must auto-update and auto-prune after every job.
- Example minimal workflow:
```yaml
name: ci
on:
push:
branches: [main]
jobs:
lint-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: {node-version: 20}
- run: npm ci && npm run lint && npm test
```
Jenkins (Declarative Pipeline)
- Use `agent { kubernetes ... }` to run jobs in isolated pods.
- Guard every stage with `post { failure { mail ... } }`.
- Do not allow freestyle jobs; enforce `Jenkinsfile` in repo root.
- Example:
```groovy
pipeline {
agent any
stages {
stage('Build') {
steps {
sh './gradlew build'
}
}
}
}
```
Argo CD / Flux CD (GitOps Delivery)
- Application CRs must reference Helm or Kustomize sources with fixed commit SHA.
- Enable auto-sync only for dev namespaces; use manual wave + promotion PR for staging/prod.
- Enforce PR approval by at least two reviewers for manifests under `clusters/prod/**`.
Additional Sections
Testing
- Minimum stages: `lint` -> `unit` -> `integration` -> `e2e`.
- Unit tests must complete < 60s; long-running suites go behind feature flags and run nightly.
- Use service containers or Docker-Compose for deterministic integration tests; avoid external shared DB.
- Collect coverage reports and upload as PR annotations.
Performance & Scalability
- Cache dependencies (npm, pip, Maven) between jobs using checksum keys; prune weekly.
- Parallelize independent suites via matrix or `pytest -n auto`.
- Auto-scale runners via Kubernetes Cluster Autoscaler or AWS Fargate to maintain < 5 min average queue time.
- Use predictive analysis (e.g., GitHub Actions Insights, Jenkins Build Trends) to catch flaky stages.
Security
- Secrets: store in Vault, GitHub/GitLab Secret Store, or AWS Secrets Manager; never echo.
- Include SCA (`trivy fs`) and SAST (`semgrep`) steps gated on severity.
- Sign container images with cosign and enforce verification in admission controller.
- Dependency pinning via Renovate Bot with `automergeType=minor` for dev dependencies.
- Enable OIDC-based federation so runners obtain short-lived cloud credentials (no long-lived keys).
Release Strategies
- Provide both Canary and Blue/Green templates; selection by variable `strategy`.
- Canary example snippet (Kubernetes):
```yaml
apiVersion: flagger.app/v1beta1
kind: Canary
metadata: {name: backend}
spec:
targetRef:
apiVersion: apps/v1
kind: Deployment
name: backend
analysis:
threshold: 2
stepWeight: 10
maxWeight: 50
```
Monitoring & Observability
- Export pipeline metrics to Prometheus using exporters (`jenkins_exporter`, `actions-exporter`).
- Dashboard success rate, duration P95, queue time, and resource burn per build.
- Log shipping via fluent-bit on self-hosted runners; include build id labels.
Documentation & Onboarding
- Every repo must contain `docs/ci-cd.md` explaining pipeline, secrets, and release flow.
- Provide `make ci` that mirrors CI locally using `act` (GitHub) or `gitlab-runner exec docker` (GitLab).
- Maintain `CHANGELOG.md` generated at release time using conventional commits (`semantic-release`).
Common Pitfalls & Mitigations
- Flaky tests → tag and quarantine; fail build if flake rate > 3%.
- Long runner startup times → use pre-baked AMIs or Docker images containing toolchains.
- Environment drift → provision via Terraform & run `terraform validate` in CI; schedule nightly drift detection.
File/Directory Conventions
- `/.github/workflows/*.yml` – GitHub Actions
- `/ci/jenkins/Jenkinsfile` – Jenkins multibranch
- `/infrastructure/terraform/**` – IaC
- `/charts/**` or `/deploy/kustomize/**` – Kubernetes manifests