docs: update token scope examples and document deploy modes

2 files · +28 -3

M docs/cli/push.md +9 -0


@@ -63,6 +63,15 @@ When used with `--remote`, gordon push authenticates in two ways:
63	63
64	64		This means CI/CD pipelines only need a single secret (`GORDON_TOKEN`).
65	65
	66	+	### Deploy Modes
	67	+
	68	+	When the token has `admin:config:write` scope, the CLI manages deployment explicitly
	69	+	(DeployIntent → push → Deploy). This gives the CLI control over deploy timing.
	70	+
	71	+	When the token lacks `admin:config:write`, the CLI pushes the image and the server
	72	+	auto-deploys when it receives it via its event listener. The CLI logs:
	73	+	`info: deploy intent skipped (insufficient scope), server will auto-deploy on image receive`
	74	+
66	75		### Version Auto-Detection
67	76
68	77		Gordon reads version tags from CI environment variables (in priority order):


@@ -63,6 +63,15 @@ When used with `--remote`, gordon push authenticates in two ways:
63		63
64	This means CI/CD pipelines only need a single secret (`GORDON_TOKEN`).	64		This means CI/CD pipelines only need a single secret (`GORDON_TOKEN`).
65		65
		66	+	### Deploy Modes
		67	+
		68	+	When the token has `admin:config:write` scope, the CLI manages deployment explicitly
		69	+	(DeployIntent → push → Deploy). This gives the CLI control over deploy timing.
		70	+
		71	+	When the token lacks `admin:config:write`, the CLI pushes the image and the server
		72	+	auto-deploys when it receives it via its event listener. The CLI logs:
		73	+	`info: deploy intent skipped (insufficient scope), server will auto-deploy on image receive`
		74	+
66	### Version Auto-Detection	75		### Version Auto-Detection
67		76
68	Gordon reads version tags from CI environment variables (in priority order):	77		Gordon reads version tags from CI environment variables (in priority order):

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


@@ -84,18 +84,34 @@ Gordon's registry is served through the main gordon domain over HTTPS on port 44
84	84
85	85		## Token Setup
86	86
	87	+	See the examples below for the right scopes for each workflow.
	88	+
87	89		```bash
88		-	# For gordon push (recommended) — needs admin scopes for route resolution and deploy
	90	+	# Minimum scope for gordon push — route lookup + registry push
	91	+	# Server auto-deploys when it receives the image
	92	+	gordon auth token generate \
	93	+	--subject ci-bot \
	94	+	--scopes "push,pull,admin:routes:read" \
	95	+	--expiry 90d
	96	+
	97	+	# With explicit CLI-managed deploy (adds config:write for deploy control)
89	98		gordon auth token generate \
90	99		--subject ci-bot \
91	100		--scopes "push,pull,admin:routes:read,admin:config:write" \
92		-	--expiry 0
	101	+	--expiry 90d
	102	+
	103	+	# Scoped to a specific repository
	104	+	gordon auth token generate \
	105	+	--subject ci-bot \
	106	+	--repo myapp \
	107	+	--scopes "push,pull,admin:routes:read" \
	108	+	--expiry 90d
93	109
94	110		# For docker push — registry scopes only
95	111		gordon auth token generate \
96	112		--subject ci-bot \
97	113		--scopes "push,pull" \
98		-	--expiry 0
	114	+	--expiry 90d
99	115		```
100	116
101	117		Set the generated token as `GORDON_TOKEN` in your CI environment.

 ## Token Setup
+See the examples below for the right scopes for each workflow.
 ```bash
-# For gordon push (recommended) — needs admin scopes for route resolution and deploy
+# Minimum scope for gordon push — route lookup + registry push
+# Server auto-deploys when it receives the image
+gordon auth token generate \
+  --subject ci-bot \
+  --scopes "push,pull,admin:routes:read" \
+  --expiry 90d
+# With explicit CLI-managed deploy (adds config:write for deploy control)
 gordon auth token generate \
   --subject ci-bot \
   --scopes "push,pull,admin:routes:read,admin:config:write" \
-  --expiry 0
+  --expiry 90d
+# Scoped to a specific repository
+gordon auth token generate \
+  --subject ci-bot \
+  --repo myapp \
+  --scopes "push,pull,admin:routes:read" \
+  --expiry 90d
 # For docker push — registry scopes only
 gordon auth token generate \
   --subject ci-bot \
   --scopes "push,pull" \
-  --expiry 0
+  --expiry 90d
 ```
 Set the generated token as `GORDON_TOKEN` in your CI environment.