Django CI/CD Pipeline Checklist

Problem statement

A CI/CD pipeline is only as good as the checks it runs and the guarantees it enforces. Many Django pipelines run tests on SQLite, skip migration checks, rebuild the image separately for production, and deploy without smoke tests or a rehearsed rollback. Each gap eventually lets a broken release reach users. This checklist covers what a Django pipeline should verify on every change and every deploy, regardless of whether it runs on GitHub Actions, GitLab, Jenkins, or another system.

1. Run tests against the same database engine and major version as production.
2. Fail on missing migrations (makemigrations --check) and on unsafe settings (check --deploy).
3. Lint, type-check if used, and scan dependencies and images for vulnerabilities.
4. Build one artefact (image or package) per commit and promote it through environments.
5. Run migrations once per release before switching traffic, with backward-compatible changes.
6. Smoke-test after deploy, keep an approval gate for production, and rehearse rollback.

Checklist

Every pull request

• Tests run on PostgreSQL (or your production engine) as a service container.
• python manage.py makemigrations --check --dry-run fails the build on missing migrations.
• Migration linting (for example django-migration-linter or review rules) flags dangerous operations.
• Linters and formatters (ruff, black) and optional type checks pass.
• Dependency audit (pip-audit or Trivy fs) for known vulnerabilities.
• Query-count tests on critical endpoints catch N+1 regressions.

Build

• One image built per commit, tagged with the commit SHA; no rebuild for production.
• collectstatic and frontend builds happen in the image build.
• Image scanned; build cache used for speed.
• Secrets never baked into images; build-time secrets via BuildKit mounts only.

Deploy

• Deploys run only from the main branch (or tags) after all checks pass.
• Staging receives the same image first; production requires approval or a protected environment.
• Migrations run once per release (Job, release phase, or deploy step) before traffic switches.
• Rolling or blue-green switch with health checks; workers and Beat restarted with the same version.
• Deploys are serialised so two releases never run concurrently.

Verification and rollback

• Automated smoke tests after deploy (health endpoint, login, a key page) fail the pipeline if broken.
• Error rate and latency watched for a period after release (Sentry release tracking, APM).
• Rollback is a documented, rehearsed command (previous image tag or release directory).
• Release notes or deploy annotations record what shipped and when.

Secrets and access

• Pipeline secrets stored in the CI secret store or fetched via OIDC from the cloud; no long-lived keys where avoidable.
• Production credentials available only to production deploy jobs.
• Pull requests from forks cannot access secrets.

Explanation

Continuous integration verifies that each change is correct on its own; continuous delivery makes releasing that change routine and reversible. For Django, the critical additions to generic CI are database realism (SQLite hides many PostgreSQL behaviours), migration discipline (missing or unsafe migrations are a common outage cause), and release ordering (schema before code, all processes on the same version). Building one artefact and verifying it after deploy closes the gap between what was tested and what runs.

Edge cases / notes

• Monorepos should run Django checks only when relevant paths change, but always on main.
• Preview environments per pull request are an extension: same image, isolated database.
• Database-heavy migrations may need a manual or scheduled step outside the automatic pipeline.
• Feature flags let you deploy code before enabling it, reducing release risk further.

Next steps

• Implement it with Deploy Django With GitHub Actions CI/CD.
• Verify releases with the Django Post-Deploy Verification Checklist.

FAQ

What should a Django CI pipeline test?

Tests on the production database engine, missing migrations, deploy settings, linting, and dependency vulnerabilities.

Should production use a fresh build?

No. Promote the same image or artefact that passed tests and staging.

When should migrations run in a pipeline?

Once per release, before traffic switches to the new code, using backward-compatible changes.

How do I make rollbacks safe?

Keep previous artefacts, keep migrations backward compatible, and rehearse the rollback command.