Push Command

Tag, push, and optionally deploy an image to the Gordon registry.

gordon push

Synopsis

gordon push [image] [options]

Arguments

Options

Description

gordon push resolves the target image from the backend, tags it for the Gordon registry, pushes it, and optionally deploys it.

Image resolution order:

1. If --domain is provided, uses domain-based route lookup
2. If an image name is provided as argument, resolves domain(s) from the backend
3. If no argument, auto-detects from Dockerfile gordon.domain label or current directory name

To push attachment images (databases, caches, etc.), use gordon attachments push.

• For first deploys, run gordon bootstrap first to create or update the route, attachments, and secrets, then run gordon push to upload and deploy the image.
• The registry and repository are derived from the route image on the server.
• The version tag defaults to a CI tag ref (like refs/tags/v1.2.3) when available, then falls back to git describe --tags --dirty (for example v1.2.3-4-gabc1234 or v1.2.3-dirty). If no tag is found, latest is used.
• When --build is set, the command builds with docker buildx build --load and injects VERSION, GIT_TAG, GIT_SHA, and BUILD_TIME into the build environment plus any --build-arg values. To use these in your Dockerfile, declare them with ARG (e.g., ARG VERSION) then reference via ENV or in build steps.
• Use -f/--file to build from a Dockerfile outside the current directory root.
• The version tag and latest are both pushed (unless the version is latest).

Authentication

When used with --remote, gordon push authenticates in two ways:

• Admin API (route resolution, deploy): uses --token or $GORDON_TOKEN as Bearer token
• Registry push: automatically exchanges the token for a short-lived (5 min) registry access token via /auth/token -- no docker login required

This means CI/CD pipelines only need a single secret (GORDON_TOKEN).

Deploy Modes

When the token has admin:config:write scope, the CLI manages deployment explicitly (DeployIntent → push → Deploy). This gives the CLI control over deploy timing.

When the token lacks admin:config:write, the CLI pushes the image and the server auto-deploys when it receives it via its event listener. The CLI logs: info: deploy intent skipped (insufficient scope), server will auto-deploy on image receive

Version Auto-Detection

Gordon reads version tags from CI environment variables (in priority order):

Examples

# Build, push, and deploy (auto-detect image name)
gordon push --build --remote https://gordon.example.com --no-confirm

# Specify image name explicitly
gordon push myapp --build --remote https://gordon.example.com --no-confirm

# Push existing local image, skip deploy
gordon push myapp --tag v1.2.0 --no-deploy

# Push and deploy without confirmation
gordon push myapp --no-confirm

# Build for ARM and pass build args
gordon push myapp --build --platform linux/arm64 --build-arg CGO_ENABLED=0

# Build from a custom Dockerfile path
gordon push myapp --build -f docker/app/Dockerfile

# CI/CD usage (single env var, no docker login needed)
export GORDON_TOKEN="your-token"
gordon push --build --remote https://gordon.example.com --no-confirm

Notes

• Remote mode required. See CLI Overview for targeting options.
• gordon push requires the route to already exist so it can resolve the target image. Use gordon bootstrap for first deploys.
• --build requires Docker with Buildx. Docker Desktop includes it; on Linux, install the docker-buildx-plugin package.
• Gordon uses native registry uploads instead of shelling out to docker push. Image layers are sent in 50MB chunks, which stays under Cloudflare's 100MB per-request limit so proxied pushes keep working. Keep the server's max_blob_chunk_size larger than the client chunk size; the default 95MB works out of the box.

Related

• CLI Overview
• Deployment Overview
• GitHub Actions
• Attachments Commands
• Routes Command
• Authentication