Push Command

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

gordon push

Synopsis

gordon push [image] [options]

Arguments

Argument	Description
`[image]`	Image name to push (optional). If omitted, auto-detected from Dockerfile labels or current directory name

Options

Option	Description
`--build`	Build the image first using `docker buildx`
`-f, --file`	Path to Dockerfile (default: `./Dockerfile`, used with `--build`)
`--platform`	Target platform for buildx (default: `linux/amd64`)
`--build-arg`	Additional build args (repeatable, `KEY=VALUE`)
`--tag`	Override pushed version tag (default: tag ref from CI, then `git describe --tags --dirty`)
`--no-confirm`	Skip deploy confirmation prompt
`--no-deploy`	Push only; skip deployment prompt
`--domain`	Explicit deploy target override
`--remote, -r`	Remote name or URL (e.g., prod, https://gordon.mydomain.com)
`--token`	Authentication token for remote

Description

gordon push tags the selected image for the Gordon registry, pushes it, and optionally deploys matching routes.

Image resolution order:

--domain is the explicit deploy target override for legacy workflows
Positional refs resolve routes by image name; tagged refs still use the image name for lookup
Dotted positional refs probe image routes first, then fall back to legacy domain lookup
No-arg mode auto-detects from the Dockerfile label or current directory

The pushed version still comes from --tag, CI tag refs, or git describe --tags --dirty.

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):

CI System	Variable	Example
GitHub Actions	`$GITHUB_REF`	`refs/tags/v1.2.0`
GitHub Actions	`$GITHUB_REF_TYPE` + `$GITHUB_REF_NAME`	`tag` + `v1.2.0`
GitLab CI	`$CI_COMMIT_TAG`	`v1.2.0`
Azure DevOps	`$BUILD_SOURCEBRANCH`	`refs/tags/v1.2.0`
Any	`git describe --tags`	`v1.2.3-4-gabc1234`
Fallback	-	`latest`

Examples

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

# Push an image and deploy it
gordon push myapp --remote https://gordon.example.com --no-confirm

# Push and deploy to an explicit domain
gordon push myapp:latest --domain app.example.com --remote https://gordon.example.com --no-confirm

# Tagged refs still resolve routes by image name
gordon push myapp:v1.2.3 --tag v1.2.3 --no-deploy

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

# 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

# Legacy compatibility: domain-looking positional target
gordon push app.example.com --no-confirm

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

Notes

Remote mode required. See CLI Overview for targeting options.
gordon push requires the target route to already exist so it can resolve the deploy target. 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.

source

1# Push Command
2
3Tag, push, and optionally deploy an image to the Gordon registry.
4
5## gordon push
6
7### Synopsis
8
9```bash
10gordon push [image] [options]
11```
12
13### Arguments
14
15| Argument | Description |
16|----------|-------------|
17| `[image]` | Image name to push (optional). If omitted, auto-detected from Dockerfile labels or current directory name |
18
19### Options
20
21| Option | Description |
22|--------|-------------|
23| `--build` | Build the image first using `docker buildx` |
24| `-f, --file` | Path to Dockerfile (default: `./Dockerfile`, used with `--build`) |
25| `--platform` | Target platform for buildx (default: `linux/amd64`) |
26| `--build-arg` | Additional build args (repeatable, `KEY=VALUE`) |
27| `--tag` | Override pushed version tag (default: tag ref from CI, then `git describe --tags --dirty`) |
28| `--no-confirm` | Skip deploy confirmation prompt |
29| `--no-deploy` | Push only; skip deployment prompt |
30| `--domain` | Explicit deploy target override |
31| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
32| `--token` | Authentication token for remote |
33
34### Description
35
36`gordon push` tags the selected image for the Gordon registry, pushes it, and
37optionally deploys matching routes.
38
39Image resolution order:
401. `--domain` is the explicit deploy target override for legacy workflows
412. Positional refs resolve routes by image name; tagged refs still use the image name for lookup
423. Dotted positional refs probe image routes first, then fall back to legacy domain lookup
434. No-arg mode auto-detects from the Dockerfile label or current directory
44
45The pushed version still comes from `--tag`, CI tag refs, or `git describe --tags --dirty`.
46
47To push attachment images (databases, caches, etc.), use `gordon attachments push`.
48
49- 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.
50- The registry and repository are derived from the route image on the server.
51- The version tag defaults to a CI tag ref (like `refs/tags/v1.2.3`) when available,
52  then falls back to `git describe --tags --dirty` (for example
53  `v1.2.3-4-gabc1234` or `v1.2.3-dirty`). If no tag is found, `latest` is used.
54- When `--build` is set, the command builds with `docker buildx build --load`
55  and injects `VERSION`, `GIT_TAG`, `GIT_SHA`, and `BUILD_TIME` into the build
56  environment plus any `--build-arg` values. To use these in your Dockerfile,
57  declare them with `ARG` (e.g., `ARG VERSION`) then reference via `ENV` or
58  in build steps.
59- Use `-f/--file` to build from a Dockerfile outside the current directory root.
60- The version tag and `latest` are both pushed (unless the version is `latest`).
61
62### Authentication
63
64When used with `--remote`, gordon push authenticates in two ways:
65
66- **Admin API** (route resolution, deploy): uses `--token` or `$GORDON_TOKEN` as Bearer token
67- **Registry push**: automatically exchanges the token for a short-lived (5 min) registry access token via `/auth/token` -- no `docker login` required
68
69This means CI/CD pipelines only need a single secret (`GORDON_TOKEN`).
70
71### Deploy Modes
72
73When the token has `admin:config:write` scope, the CLI manages deployment explicitly
74(DeployIntent → push → Deploy). This gives the CLI control over deploy timing.
75
76When the token lacks `admin:config:write`, the CLI pushes the image and the server
77auto-deploys when it receives it via its event listener. The CLI logs:
78`info: deploy intent skipped (insufficient scope), server will auto-deploy on image receive`
79
80### Version Auto-Detection
81
82Gordon reads version tags from CI environment variables (in priority order):
83
84| CI System | Variable | Example |
85|-----------|----------|---------|
86| GitHub Actions | `$GITHUB_REF` | `refs/tags/v1.2.0` |
87| GitHub Actions | `$GITHUB_REF_TYPE` + `$GITHUB_REF_NAME` | `tag` + `v1.2.0` |
88| GitLab CI | `$CI_COMMIT_TAG` | `v1.2.0` |
89| Azure DevOps | `$BUILD_SOURCEBRANCH` | `refs/tags/v1.2.0` |
90| Any | `git describe --tags` | `v1.2.3-4-gabc1234` |
91| Fallback | - | `latest` |
92
93### Examples
94
95```bash
96# Build, push, and deploy (auto-detect image name)
97gordon push --build --remote https://gordon.example.com --no-confirm
98
99# Push an image and deploy it
100gordon push myapp --remote https://gordon.example.com --no-confirm
101
102# Push and deploy to an explicit domain
103gordon push myapp:latest --domain app.example.com --remote https://gordon.example.com --no-confirm
104
105# Tagged refs still resolve routes by image name
106gordon push myapp:v1.2.3 --tag v1.2.3 --no-deploy
107
108# Push existing local image, skip deploy
109gordon push myapp --tag v1.2.0 --no-deploy
110
111# Build for ARM and pass build args
112gordon push myapp --build --platform linux/arm64 --build-arg CGO_ENABLED=0
113
114# Build from a custom Dockerfile path
115gordon push myapp --build -f docker/app/Dockerfile
116
117# Legacy compatibility: domain-looking positional target
118gordon push app.example.com --no-confirm
119
120# CI/CD usage (single env var, no docker login needed)
121export GORDON_TOKEN="your-token"
122gordon push myapp --build --remote https://gordon.example.com --no-confirm
123```
124
125### Notes
126
127- Remote mode required. See [CLI Overview](./index.md) for targeting options.
128- `gordon push` requires the target route to already exist so it can resolve the deploy target.
129  Use `gordon bootstrap` for first deploys.
130- `--build` requires Docker with Buildx. Docker Desktop includes it; on Linux,
131  install the `docker-buildx-plugin` package.
132- Gordon uses native registry uploads instead of shelling out to `docker push`.
133  Image layers are sent in 50MB chunks, which stays under Cloudflare's 100MB
134  per-request limit so proxied pushes keep working. Keep the server's
135  `max_blob_chunk_size` larger than the client chunk size; the default `95MB`
136  works out of the box.
137
138## Related
139
140- [CLI Overview](./index.md)
141- [Deployment Overview](../deployment/index.md)
142- [GitHub Actions](../deployment/github-actions.md)
143- [Attachments Commands](./attachments.md)
144- [Routes Command](./routes.md)
145- [Authentication](../config/auth.md)

push.md RawHistoryFolder