cfa771f docs(auth): document the admin scope gordon images push needs (#13) · gordon

M docs/cli/auth.md +2 -2


@@ -294,8 +294,8 @@ Usage:
294	294		### CI/CD Setup
295	295
296	296		```bash
297		-	# Generate token for CI
298		-	gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
	297	+	# Generate token for CI (gordon images push needs one admin scope)
	298	+	gordon auth token generate --subject ci-bot --scopes push,pull,admin:apps:read --expiry 0
299	299
300	300		# Save token as CI secret
301	301		# GitHub: Settings > Secrets > New repository secret


@@ -294,8 +294,8 @@ Usage:
294		### CI/CD Setup	294		### CI/CD Setup
295			295
296		```bash	296		```bash
297	-	# Generate token for CI	297	+	# Generate token for CI (gordon images push needs one admin scope)
298	-	gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0	298	+	gordon auth token generate --subject ci-bot --scopes push,pull,admin:apps:read --expiry 0
299			299
300		# Save token as CI secret	300		# Save token as CI secret
301		# GitHub: Settings > Secrets > New repository secret	301		# GitHub: Settings > Secrets > New repository secret

M docs/cli/images.md +4 -1


@@ -87,7 +87,10 @@ When used with `--remote`, gordon images push authenticates in two ways:
87	87		- Admin API (tag listing for inference): uses `--token` or `$GORDON_TOKEN` as Bearer token
88	88		- Registry push: automatically exchanges the token for a short-lived (5 min) registry access token via `/auth/token` -- no `docker login` required
89	89
90		-	This means CI/CD pipelines only need a single secret (`GORDON_TOKEN`).
	90	+	This means CI/CD pipelines only need a single secret (`GORDON_TOKEN`). The token
	91	+	needs `push` plus at least one `admin:*` scope, because the admin API rejects
	92	+	tokens without one; `push,pull,admin:apps:read` is the minimum. A `push,pull`
	93	+	token only works with `docker login` and `docker push`.
91	94
92	95		### Version Auto-Detection
93	96


@@ -87,7 +87,10 @@ When used with `--remote`, gordon images push authenticates in two ways:
87		- Admin API (tag listing for inference): uses `--token` or `$GORDON_TOKEN` as Bearer token	87		- Admin API (tag listing for inference): uses `--token` or `$GORDON_TOKEN` as Bearer token
88		- Registry push: automatically exchanges the token for a short-lived (5 min) registry access token via `/auth/token` -- no `docker login` required	88		- Registry push: automatically exchanges the token for a short-lived (5 min) registry access token via `/auth/token` -- no `docker login` required
89			89
90	-	This means CI/CD pipelines only need a single secret (`GORDON_TOKEN`).	90	+	This means CI/CD pipelines only need a single secret (`GORDON_TOKEN`). The token
			91	+	needs `push` plus at least one `admin:*` scope, because the admin API rejects
			92	+	tokens without one; `push,pull,admin:apps:read` is the minimum. A `push,pull`
			93	+	token only works with `docker login` and `docker push`.
91			94
92		### Version Auto-Detection	95		### Version Auto-Detection
93			96

M docs/deployment/generic-ci.md +2 -1


@@ -166,7 +166,8 @@ Use the minimum scopes for the steps the pipeline performs. A repository restric
166	166		\| Workflow \| Required Scopes \|
167	167		\|----------\|----------------\|
168	168		\| Build + push, then apply + deploy \| `push,pull,admin:apps:read,admin:apps:write` \|
169		-	\| Push only (no deploy) \| `push,pull` \|
	169	+	\| `gordon images push` only (no deploy) \| `push,pull,admin:apps:read` \|
	170	+	\| `docker push` only (no deploy) \| `push,pull` \|
170	171		\| docker push, then apply + deploy \| `push,pull` + `admin:apps:read,admin:apps:write` for the CLI step \|
171	172
172	173		## Troubleshooting


@@ -166,7 +166,8 @@ Use the minimum scopes for the steps the pipeline performs. A repository restric
166		\| Workflow \| Required Scopes \|	166		\| Workflow \| Required Scopes \|
167		\|----------\|----------------\|	167		\|----------\|----------------\|
168		\| Build + push, then apply + deploy \| `push,pull,admin:apps:read,admin:apps:write` \|	168		\| Build + push, then apply + deploy \| `push,pull,admin:apps:read,admin:apps:write` \|
169	-	\| Push only (no deploy) \| `push,pull` \|	169	+	\| `gordon images push` only (no deploy) \| `push,pull,admin:apps:read` \|
			170	+	\| `docker push` only (no deploy) \| `push,pull` \|
170		\| docker push, then apply + deploy \| `push,pull` + `admin:apps:read,admin:apps:write` for the CLI step \|	171		\| docker push, then apply + deploy \| `push,pull` + `admin:apps:read,admin:apps:write` for the CLI step \|
171			172
172		## Troubleshooting	173		## Troubleshooting

M docs/deployment/index.md +9 -3


@@ -77,19 +77,25 @@ Clients use the main Gordon domain over HTTPS, normally on port 443. Gordon bind
77	77		See the examples below for the right scopes for each workflow.
78	78
79	79		```bash
80		-	# Push only — registry scopes
	80	+	# docker push only — registry scopes
81	81		gordon auth token generate \
82	82		--subject ci-bot \
83	83		--scopes "push,pull" \
84	84		--expiry 90d
85	85
	86	+	# gordon images push only — the CLI also needs one admin scope
	87	+	gordon auth token generate \
	88	+	--subject ci-bot \
	89	+	--scopes "push,pull,admin:apps:read" \
	90	+	--expiry 90d
	91	+
86	92		# Push + apply/deploy — adds app mutation scopes
87	93		gordon auth token generate \
88	94		--subject ci-bot \
89	95		--scopes "push,pull,admin:apps:read,admin:apps:write" \
90	96		--expiry 90d
91	97
92		-	# Repository-scoped registry token for push only
	98	+	# Repository-scoped registry token for docker push only
93	99		gordon auth token generate \
94	100		--subject ci-bot \
95	101		--repo myapp \

@@ -97,7 +103,7 @@ gordon auth token generate \
97	103		--expiry 90d
98	104		```
99	105
100		-	Set the generated token as `GORDON_TOKEN` in your CI environment. `--repo` limits registry push/pull to that repository; it does not constrain `admin:*` scopes. Use a separate least-privilege token for app administration when repository and deployment duties must be isolated.
	106	+	Set the generated token as `GORDON_TOKEN` in your CI environment. `gordon images push` calls the admin API before it exchanges the token for registry access, so its token needs at least one `admin:` scope; `admin:apps:read` is the smallest. `--repo` limits registry push/pull to that repository; it does not constrain `admin:` scopes. Use a separate least-privilege token for app administration when repository and deployment duties must be isolated.
101	107
102	108		## Version Strategies
103	109

 See the examples below for the right scopes for each workflow.
 ```bash
-# Push only — registry scopes
+# docker push only — registry scopes
 gordon auth token generate \
   --subject ci-bot \
   --scopes "push,pull" \
   --expiry 90d
+# gordon images push only — the CLI also needs one admin scope
+gordon auth token generate \
+  --subject ci-bot \
+  --scopes "push,pull,admin:apps:read" \
+  --expiry 90d
 # Push + apply/deploy — adds app mutation scopes
 gordon auth token generate \
   --subject ci-bot \
   --scopes "push,pull,admin:apps:read,admin:apps:write" \
   --expiry 90d
-# Repository-scoped registry token for push only
+# Repository-scoped registry token for docker push only
 gordon auth token generate \
   --subject ci-bot \
   --repo myapp \
   --expiry 90d
 ```
-Set the generated token as `GORDON_TOKEN` in your CI environment. `--repo` limits registry push/pull to that repository; it does not constrain `admin:*` scopes. Use a separate least-privilege token for app administration when repository and deployment duties must be isolated.
+Set the generated token as `GORDON_TOKEN` in your CI environment. `gordon images push` calls the admin API before it exchanges the token for registry access, so its token needs at least one `admin:*` scope; `admin:apps:read` is the smallest. `--repo` limits registry push/pull to that repository; it does not constrain `admin:*` scopes. Use a separate least-privilege token for app administration when repository and deployment duties must be isolated.
 ## Version Strategies