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