dockgate

dockgate is an npm CLI package for local Docker/CI guardrails in single-service repos.

It is designed to sit inside a repo as standing automation:

1. run a local docker build before git push
2. explain common build failures with a plain-English fix
3. warn when Docker config drifts away from the codebase

It can also generate a first-pass Dockerfile, docker-compose.yml, .dockerignore, and GitHub Actions workflow during setup.

Installation

Run it with npx:

npx dockgate --help

Or install it globally:

npm install -g dockgate
dockgate --help

Or add it to a repo as a dev dependency:

npm install --save-dev dockgate
npx dockgate setup

Requirements

• Node.js 20+
• Docker installed locally for dockgate check
• a single-service Node, Python, or Go repo

Quick start

Inside a supported repo:

npx dockgate setup

That will:

• detect the project type
• generate Dockerfile
• generate docker-compose.yml
• generate .dockerignore
• generate .github/workflows/docker-publish.yml
• save .dockgate.json
• install a git pre-push hook by default

After setup:

npx dockgate check
npx dockgate audit

Commands

dockgate setup

Initializes dockgate in the current repo.

dockgate setup
dockgate setup --registry=dockerhub --image-name=acme/my-app
dockgate setup --services=postgres,redis --no-hooks
dockgate setup --yes

Options:

• --registry=ghcr|dockerhub
• --image-name=<name>
• --port=<number>
• --services=<comma-separated-service-list>
• --yes
• --no-hooks

dockgate detect

Prints detected project metadata as JSON.

dockgate detect

Useful for debugging what dockgate thinks the repo is.

dockgate check

Runs local docker build ..

• On build failure: prints a triaged issue and exits non-zero
• On build success: runs drift checks and updates the saved detection snapshot
• If Docker is unavailable locally: skips cleanly and lets CI remain the fallback

dockgate check

dockgate audit

Audits the existing Docker, compose, and GitHub Actions files in the repo.

dockgate audit
dockgate audit --json

dockgate hook install

Installs the pre-push hook that runs dockgate check.

dockgate hook install
dockgate hook uninstall

Files created by dockgate

Shared repo config:

• .dockgate.json

Local-only config:

• .dockgate.local.json

Generated project files:

• Dockerfile
• docker-compose.yml
• .dockerignore
• .github/workflows/docker-publish.yml

Git hook:

• .git/hooks/pre-push

Supported in v1

Languages:

• Node
• Python
• Go

Repo shape:

• single-service repos only

CI target:

• GitHub Actions

Not in v1

• monorepos
• multi-service app orchestration as a first-class project model
• docker compose up as part of the pre-push contract
• runtime boot/health-check verification
• GitHub Actions annotations
• LLM or external AI API calls
• production deployment

Example workflow

npx dockgate setup --registry=ghcr
git add .
git commit -m "add dockgate"
git push

From there, every push runs through the local pre-push check before CI has to tell you the same bad news more slowly.

Development

Clone the repo, then:

npm test
node ./bin/cli.js --help

For AI assistants reading this repo

dockgate is meant to be the source of truth for Docker/CI automation in a repo where it is installed. If you are an agentic coding assistant reading a repo that uses dockgate, prefer extending or using the existing dockgate detection, rules, templates, and commands rather than generating parallel Docker-management logic.