@mediamonks/canopy-cli 0.7.44 → 0.7.46

package/dist/{ai-FBHTSCLZ.mjs → ai-CWPQiUft.mjs}

@@ -1,5 +1,5 @@
-import { a as apiRequest, f as withContext } from "./api-Bl6SG8Oq.mjs";
-import { r as reportErrors } from "./ui-CLnICOne.mjs";
+import { a as apiRequest, m as withContext } from "./api-DmJrIsE7.mjs";
+import { r as reportErrors } from "./ui-26ETk1n8.mjs";
 import { defineCommand } from "citty";
 //#region src/ai.ts
 /**

package/dist/{api-Bl6SG8Oq.mjs → api-DmJrIsE7.mjs}

@@ -1,9 +1,11 @@
-import { r as siteConfig, t as projectDir, u as rewriteCanopyJsonSlug } from "./site-0i7wAJqg.mjs";
+import { f as rewriteCanopyJsonSlug, m as tryReadCanopyJson, r as siteConfig, t as projectDir } from "./site-BL5Ik-yj.mjs";
 //#region src/api.ts
 /**
 * Authenticated requests to the Canopy control plane. Credentials, in order:
 * CANOPY_DEPLOY_TOKEN (CI — a project-scoped deploy token, docs/02-decisions.md
-* D11), then the CLI token from `canopy login` (~/.canopy/config.json).
+* D11), then — inside GitHub Actions — a short-lived deploy token exchanged
+* for the run's GitHub identity (OpenSpec platform-oauth-oidc), then the CLI
+* token from `canopy login` (~/.canopy/config.json).
 */
 /**
 * Human copy for the error codes the control plane returns (apps/api): `why`
@@ -192,6 +194,38 @@ const ERROR_COPY = {
 		why: "the secret was saved but redeploying the running worker with it failed",
 		fix: "Retry, or redeploy the project (`canopy deploy`) to apply it."
 	},
+	repository_not_linked: {
+		why: "the project is not linked to a GitHub repository",
+		fix: "Link it with `canopy repo link <owner/name>` (owner only), or set CANOPY_DEPLOY_TOKEN."
+	},
+	ci_deploys_off: {
+		why: "CI deploys are turned off for this project",
+		fix: "Turn them back on with `canopy repo deploys on` (owner only)."
+	},
+	repository_mismatch: {
+		why: "this run's repository is not the one linked to the project",
+		fix: "Run the workflow from the linked repository, or link this one with `canopy repo link` (`canopy repo show` names the current link)."
+	},
+	ref_not_allowed: {
+		why: "this run's branch is neither the project's live branch nor its staging branch",
+		fix: "Deploy from the linked branch, or change it with `canopy repo branches --ref <ref>` (`canopy repo show` names both)."
+	},
+	invalid_id_token: {
+		why: "the platform did not accept this run's GitHub identity — it comes from another GitHub host than the linked repository's, or was minted for another Canopy site",
+		fix: "Check `canopy repo show` names this repository's host, and that the workflow deploys to the site canopy.json pins."
+	},
+	channel_not_allowed: {
+		why: "this run is on the project's staging branch, which only deploys to staging",
+		fix: "Deploy, promote or roll back live from the live branch, or by hand after `canopy login`."
+	},
+	invalid_repository: {
+		why: "the repository must be written as owner/name",
+		fix: "Pass it like `canopy repo link monks/my-tool` (or `monks.ghe.com/monks/my-tool` to name the host)."
+	},
+	invalid_ref: {
+		why: "branches are full git refs, and the staging branch must differ from the live one",
+		fix: "Pass e.g. `--ref refs/heads/main --staging-ref refs/heads/develop`."
+	},
 	slug_unchanged: {
 		why: "the project already has that slug",
 		fix: "Pass the new slug you want, e.g. `canopy rename my-new-name`."
@@ -369,31 +403,112 @@ async function withContext(request, context) {
 		throw err;
 	}
 }
-/** Resolve the bearer token: CI deploy token first (D11), then the login token. */
-function credentials() {
+/**
+* Resolve the bearer token: CI deploy token first (D11), then the GitHub
+* Actions exchange on a runner that may request an identity token, then the
+* login token. The exchange comes before the "Not logged in" check because a
+* runner has no ~/.canopy/config.json.
+*/
+async function credentials() {
 	const config = siteConfig();
 	const deployToken = process.env["CANOPY_DEPLOY_TOKEN"];
-	const token = deployToken || config.token;
-	if (!token) throw new Error("Not logged in — run `canopy login` first.");
+	if (deployToken) return {
+		apiUrl: config.apiUrl,
+		token: deployToken,
+		isDeployToken: true,
+		kind: "deploy-token"
+	};
+	if (onGithubActions()) {
+		if (process.env["ACTIONS_ID_TOKEN_REQUEST_URL"] || !config.token) return {
+			...await githubActionsCredentials(),
+			isDeployToken: true,
+			kind: "github-actions"
+		};
+	}
+	if (!config.token) throw new Error("Not logged in — run `canopy login` first.");
 	return {
 		apiUrl: config.apiUrl,
-		token,
-		isDeployToken: Boolean(deployToken)
+		token: config.token,
+		isDeployToken: false,
+		kind: "login"
 	};
 }
+/** Running inside a GitHub Actions job (the runner sets GITHUB_ACTIONS=true). */
+function onGithubActions(env = process.env) {
+	return Boolean(env["GITHUB_ACTIONS"]);
+}
+let exchange;
+/**
+* Trade this GitHub Actions run's OIDC token for a short-lived Canopy deploy
+* token (design D-I). Once per process: every later request reuses it, and a
+* failure stays a failure. The audience is the resolved site's API origin, so
+* the token cannot be replayed on another Canopy site (D-B). `slug` is the
+* project to deploy; it defaults to canopy.json's.
+*/
+function githubActionsCredentials(slug) {
+	exchange ??= exchangeGithubIdentity(slug);
+	return exchange;
+}
+async function exchangeGithubIdentity(slug) {
+	const { apiUrl } = siteConfig();
+	const project = slug ?? tryReadCanopyJson(projectDir())?.slug;
+	if (!project) throw new Error("No project to deploy — run from a directory with a canopy.json naming its slug, or pass --project.");
+	const requestUrl = process.env["ACTIONS_ID_TOKEN_REQUEST_URL"];
+	const requestToken = process.env["ACTIONS_ID_TOKEN_REQUEST_TOKEN"];
+	if (!requestUrl || !requestToken) throw new Error("This GitHub Actions job cannot prove which repository it runs from. Add `permissions: id-token: write` (and `contents: read`) to the workflow or job, or set CANOPY_DEPLOY_TOKEN.");
+	const audience = new URL(apiUrl).origin;
+	const oidcUrl = new URL(requestUrl);
+	oidcUrl.searchParams.set("audience", audience);
+	const oidc = await fetch(oidcUrl, { headers: { authorization: `Bearer ${requestToken}` } });
+	const idToken = oidc.ok ? (await oidc.json()).value : void 0;
+	if (!idToken) throw new Error(`GitHub did not issue an identity token for this run (HTTP ${oidc.status}). Check the workflow has \`permissions: id-token: write\`.`);
+	const path = "/auth/github-actions";
+	const response = await fetch(`${apiUrl}/control/v1${path}`, {
+		method: "POST",
+		headers: {
+			...commonHeaders(),
+			"content-type": "application/json"
+		},
+		body: JSON.stringify({
+			id_token: idToken,
+			project
+		})
+	});
+	const payload = await response.json().catch(() => ({}));
+	if (!response.ok || !payload.token) {
+		const err = new ApiError(response.status, payload.error ?? `http_${response.status}`, "POST", path, payload.detail, response.headers.get("x-canopy-request-id") ?? void 0);
+		err.context = { action: `deploy "${project}" from GitHub Actions` };
+		throw err;
+	}
+	const current = payload.slug ?? project;
+	if (current !== project) followRename(response, project);
+	return {
+		apiUrl,
+		token: payload.token,
+		slug: current,
+		channel: payload.channel === "staging" ? "staging" : "live",
+		expiresAt: payload.expires_at ?? ""
+	};
+}
+/** The 401 fix line, by what the request carried. */
+const UNAUTHENTICATED_FIX = {
+	"deploy-token": "The deploy token was rejected — it may have been revoked. Create a new one in the dashboard (Settings → Deploy tokens) or with `canopy token create`.",
+	"github-actions": "This run's short-lived deploy token was refused — CI deploys may have been turned off or the link changed while it ran. Check `canopy repo show`, then re-run the workflow.",
+	login: "Your session has expired — run `canopy login` again."
+};
 /** Turn a non-2xx response into a thrown ApiError (friendlier copy on 401). */
-async function fail(response, isDeployToken, method, path) {
+async function fail(response, kind, method, path) {
 	const payload = await response.json().catch(() => ({}));
 	const code = payload.error ?? (response.status === 401 ? "unauthenticated" : `http_${response.status}`);
 	const err = new ApiError(response.status, code, method, path, payload.detail, response.headers.get("x-canopy-request-id") ?? void 0);
 	if (response.status === 401) err.context = {
 		action: "authenticate with Canopy",
-		fixes: { [code]: isDeployToken ? "The deploy token was rejected — it may have been revoked. Create a new one in the dashboard (Settings → Deploy tokens) or with `canopy token create`." : "Your session has expired — run `canopy login` again." }
+		fixes: { [code]: UNAUTHENTICATED_FIX[kind] }
 	};
 	throw err;
 }
 async function apiRequest(method, path, body, rawContentType, headers) {
-	const { apiUrl, token, isDeployToken } = credentials();
+	const { apiUrl, token, kind } = await credentials();
 	const isForm = body instanceof FormData;
 	const response = await fetch(`${apiUrl}/control/v1${path}`, {
 		method,
@@ -406,7 +521,7 @@ async function apiRequest(method, path, body, rawContentType, headers) {
 		body: body === void 0 ? void 0 : isForm ? body : rawContentType !== void 0 ? body : JSON.stringify(body)
 	});
 	followRename(response, slugInPath(path));
-	if (!response.ok) return fail(response, isDeployToken, method, path);
+	if (!response.ok) return fail(response, kind, method, path);
 	if (response.status === 204) return void 0;
 	return await response.json();
 }
@@ -415,7 +530,7 @@ async function apiRequest(method, path, body, rawContentType, headers) {
 * the bytes itself, so `contentType` is a hint, not a claim it trusts.
 */
 async function apiUpload(path, bytes, contentType) {
-	const { apiUrl, token, isDeployToken } = credentials();
+	const { apiUrl, token, kind } = await credentials();
 	const response = await fetch(`${apiUrl}/control/v1${path}`, {
 		method: "POST",
 		headers: {
@@ -426,18 +541,18 @@ async function apiUpload(path, bytes, contentType) {
 		body: bytes
 	});
 	followRename(response, slugInPath(path));
-	if (!response.ok) return fail(response, isDeployToken, "POST", path);
+	if (!response.ok) return fail(response, kind, "POST", path);
 	return await response.json();
 }
 /** Authenticated GET returning raw bytes (e.g. a deploy zip). */
 async function apiDownload(path) {
-	const { apiUrl, token, isDeployToken } = credentials();
+	const { apiUrl, token, kind } = await credentials();
 	const response = await fetch(`${apiUrl}/control/v1${path}`, { headers: {
 		...commonHeaders(),
 		authorization: `Bearer ${token}`
 	} });
 	followRename(response, slugInPath(path));
-	if (!response.ok) return fail(response, isDeployToken, "GET", path);
+	if (!response.ok) return fail(response, kind, "GET", path);
 	return Buffer.from(await response.arrayBuffer());
 }
 /**
@@ -446,7 +561,7 @@ async function apiDownload(path) {
 * re-vouches it (docs/10-cli-sites.md D17).
 */
 async function apiDataRequest(method, path, projectSlug, body, rawContentType, channel) {
-	const { apiUrl, token, isDeployToken } = credentials();
+	const { apiUrl, token, kind } = await credentials();
 	const response = await fetch(`${apiUrl}/data/v1${path}`, {
 		method,
 		headers: {
@@ -459,9 +574,9 @@ async function apiDataRequest(method, path, projectSlug, body, rawContentType, c
 		body: body === void 0 ? void 0 : rawContentType !== void 0 ? body : JSON.stringify(body)
 	});
 	followRename(response, projectSlug);
-	if (!response.ok) return fail(response, isDeployToken, method, path);
+	if (!response.ok) return fail(response, kind, method, path);
 	if (response.status === 204) return void 0;
 	return await response.json();
 }
 //#endregion
-export { apiRequest as a, credentials as c, noticeRenamesOnly as d, withContext as f, apiDownload as i, currentSlug as l, agentHeaders as n, apiUpload as o, apiDataRequest as r, commonHeaders as s, ApiError as t, followRename as u };
+export { apiRequest as a, credentials as c, githubActionsCredentials as d, noticeRenamesOnly as f, apiDownload as i, currentSlug as l, withContext as m, agentHeaders as n, apiUpload as o, onGithubActions as p, apiDataRequest as r, commonHeaders as s, ApiError as t, followRename as u };

package/dist/{browse-B8-0dweq.mjs → browse-BPLWhoFI.mjs}

@@ -1,5 +1,5 @@
-import { p as tryResolveProject, r as siteConfig } from "./site-0i7wAJqg.mjs";
-import { a as apiRequest, t as ApiError } from "./api-Bl6SG8Oq.mjs";
+import { h as tryResolveProject, r as siteConfig } from "./site-BL5Ik-yj.mjs";
+import { a as apiRequest, t as ApiError } from "./api-DmJrIsE7.mjs";
 import { defineCommand } from "citty";
 //#region src/browse.ts
 /**

package/dist/{db-BJJGydgL.mjs → db-DpCMc0uz.mjs}

@@ -1,7 +1,7 @@
-import { l as resolveProject, s as projectFlagArgs } from "./site-0i7wAJqg.mjs";
-import { a as apiRequest, f as withContext, r as apiDataRequest } from "./api-Bl6SG8Oq.mjs";
-import { a as unwrap, i as requireTty, r as reportErrors } from "./ui-CLnICOne.mjs";
-import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-D8NqjC5I.mjs";
+import { d as resolveProject, l as projectFlagArgs } from "./site-BL5Ik-yj.mjs";
+import { a as apiRequest, m as withContext, r as apiDataRequest } from "./api-DmJrIsE7.mjs";
+import { a as unwrap, i as requireTty, r as reportErrors } from "./ui-26ETk1n8.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-BReMlGWP.mjs";
 import { defineCommand } from "citty";
 import { readFileSync, writeFileSync } from "node:fs";
 import * as p from "@clack/prompts";

package/dist/{deploy-ExrIeX_m.mjs → deploy-BnRQusjJ.mjs}

@@ -1,7 +1,7 @@
-import { c as projectUrl, d as stagingUrl, f as tryReadCanopyJson, l as resolveProject, o as projectDirArgs, r as siteConfig, s as projectFlagArgs } from "./site-0i7wAJqg.mjs";
-import { a as apiRequest, f as withContext, i as apiDownload, l as currentSlug, r as apiDataRequest } from "./api-Bl6SG8Oq.mjs";
-import { a as unwrap, r as reportErrors, t as formatDateTime } from "./ui-CLnICOne.mjs";
-import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-D8NqjC5I.mjs";
+import { c as projectDirArgs, d as resolveProject, l as projectFlagArgs, m as tryReadCanopyJson, p as stagingUrl, r as siteConfig, u as projectUrl } from "./site-BL5Ik-yj.mjs";
+import { a as apiRequest, d as githubActionsCredentials, i as apiDownload, l as currentSlug, m as withContext, p as onGithubActions, r as apiDataRequest, t as ApiError } from "./api-DmJrIsE7.mjs";
+import { a as unwrap, r as reportErrors, t as formatDateTime } from "./ui-26ETk1n8.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-BReMlGWP.mjs";
 import { builtinModules } from "node:module";
 import { defineCommand } from "citty";
 import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -235,9 +235,18 @@ const deployCommand = defineCommand({
 	},
 	run: reportErrors("deploy", async ({ args }) => {
 		const { dir, slug } = resolveProject(args);
-		const channel = args.staging ? "staging" : "live";
+		let channel = args.staging ? "staging" : "live";
 		const config = tryReadCanopyJson(dir) ?? {};
 		if (config.build && args.build) await runBuild(config.build, dir);
+		if (onGithubActions() && !process.env["CANOPY_DEPLOY_TOKEN"]) {
+			const exchanged = await exchangeOrSkip(slug);
+			if (!exchanged) return;
+			p.log.info(`Authenticated as this GitHub Actions run (${exchanged.slug}).`);
+			if (exchanged.channel === "staging" && channel === "live") {
+				channel = "staging";
+				p.log.info("This run is on the project's staging branch — deploying to the staging channel.");
+			}
+		}
 		const migrations = args.migrate ? readMigrationFiles(dir) : void 0;
 		if (migrations !== void 0 && config.dialect) try {
 			const { dialect } = await apiDataRequest("GET", "/platform", slug);
@@ -396,6 +405,43 @@ function bundleLimitError(files, limits) {
 	}
 	return null;
 }
+/**
+* Exchange errors that mean "CI deploys are not on here": skip, don't fail.
+* `unauthenticated` is a site whose API predates the exchange — its auth wall
+* answers the unknown route; the exchange itself never says it (a bad token
+* is `invalid_id_token`). A project scaffolded on such a site keeps the
+* yellow skip the old secret-gated workflow gave it until the site catches up.
+*/
+const SKIP_CODES = /* @__PURE__ */ new Set([
+	"repository_not_linked",
+	"ci_deploys_off",
+	"unauthenticated"
+]);
+/**
+* The run's deploy credentials, or null after announcing a skip. A project
+* that is not linked, or whose CI deploys are off, leaves the run yellow
+* rather than red: a workflow annotation saying why and how to change it, and
+* exit 0 without deploying. Every other refusal is a failure.
+*/
+async function exchangeOrSkip(slug) {
+	try {
+		return await githubActionsCredentials(slug);
+	} catch (err) {
+		if (!(err instanceof ApiError) || !SKIP_CODES.has(err.code)) throw err;
+		const message = skipMessage(err.code, slug);
+		console.log(`::warning title=Canopy deploy skipped::${message}`);
+		p.log.warn(message);
+		return null;
+	}
+}
+function skipMessage(code, slug) {
+	if (code === "ci_deploys_off") return `CI deploys are off for "${slug}", so this run deployed nothing. The project owner can turn them back on with \`canopy repo deploys on\`.`;
+	if (code === "unauthenticated") return "This Canopy site doesn't take deploys from GitHub Actions without a token yet, so this run deployed nothing. Set a CANOPY_DEPLOY_TOKEN secret to deploy from CI.";
+	const repo = process.env["GITHUB_REPOSITORY"];
+	const server = process.env["GITHUB_SERVER_URL"];
+	const host = server ? new URL(server).host : void 0;
+	return `"${slug}" is not linked to this repository, so this run deployed nothing. The project owner can link it with \`canopy repo link ${repo ? `${host && host !== "github.com" ? `${host}/` : ""}${repo}` : "<owner/name>"}\`, or set a CANOPY_DEPLOY_TOKEN secret.`;
+}
 /** PUT each file to /data/v1/uploads/<grant> — the grant is the credential. */
 async function uploadFiles(grant, files) {
 	const { apiUrl } = siteConfig();

package/dist/{dev-Cq98yblV.mjs → dev-BmKeIdMi.mjs}

@@ -1,9 +1,9 @@
-import { a as projectDialect, f as tryReadCanopyJson, l as resolveProject, o as projectDirArgs, r as siteConfig } from "./site-0i7wAJqg.mjs";
-import { a as apiRequest, f as withContext, t as ApiError } from "./api-Bl6SG8Oq.mjs";
-import { r as reportErrors, t as formatDateTime } from "./ui-CLnICOne.mjs";
-import { r as readMigrationFiles } from "./migrations-D8NqjC5I.mjs";
+import { c as projectDirArgs, d as resolveProject, m as tryReadCanopyJson, r as siteConfig, s as projectDialect } from "./site-BL5Ik-yj.mjs";
+import { a as apiRequest, m as withContext, t as ApiError } from "./api-DmJrIsE7.mjs";
+import { r as reportErrors, t as formatDateTime } from "./ui-26ETk1n8.mjs";
+import { r as readMigrationFiles } from "./migrations-BReMlGWP.mjs";
 import { i as stampWorkerHeaders, n as WORKER_ATTEST_HEADER } from "./src-8vxOBOxW.mjs";
-import { a as parseAppRoleFlag } from "./roles-UM0Iiws6.mjs";
+import { a as parseAppRoleFlag } from "./roles-S2D9Id0W.mjs";
 import { n as writeDevServerRecord } from "./dev-server-file-Dk9pk4AR.mjs";
 import { createRequire } from "node:module";
 import { defineCommand } from "citty";
@@ -325,7 +325,7 @@ async function devRemote(flags, slug) {
 async function devLocal(flags, slug) {
 	let dump;
 	if (flags.pull) {
-		const { fetchProjectDump } = await import("./local-CIkL7tXP.mjs");
+		const { fetchProjectDump } = await import("./local-C9Bi9f3y.mjs");
 		console.log(`Pulling a fresh export of ${slug}${flags.staging ? " [staging]" : ""}…`);
 		dump = await fetchProjectDump(slug, flags.staging ? "staging" : "live");
 	}
@@ -342,7 +342,7 @@ async function devLocal(flags, slug) {
 	}
 	const workerAttest = randomBytes(24).toString("base64url");
 	const devRoles = await resolveDevRoles(slug, flags.asRoles);
-	const { createSandbox } = await import("./local-CIkL7tXP.mjs");
+	const { createSandbox } = await import("./local-C9Bi9f3y.mjs");
 	const sandbox = await createSandbox({
 		slug,
 		persistDir: join(flags.dir, ".canopy", "local"),

package/dist/dev-BvVlq9np.mjs

@@ -0,0 +1,2 @@
+import { n as devCommand } from "./dev-BmKeIdMi.mjs";
+export { devCommand };

package/dist/docs/ci.md

@@ -1,75 +1,137 @@
 ---
-title: CI and deploy tokens
-description: Push-to-main deploys using a project-scoped deploy token, and why we recommend deploying from your own machine instead.
+title: CI deploys
+description: Deploy on every push from GitHub Actions with no secret — link the repository once. Deploy tokens for other CI.
 ---
 
-## Our recommendation: deploy manually
+## Link, push, done
+
+A project can deploy itself from GitHub Actions. Link the repository once, and
+every push to its main branch deploys the project. There is no secret to create,
+paste or rotate: the run proves which repository and branch it comes from with
+GitHub's own sign-in, and Canopy only accepts runs from the repository you
+linked.
+
+Only the project owner (or a platform admin) can link a repository. In the
+project's folder:
+
+```bash
+canopy repo link
+```
+
+With no argument it links the repository the folder's `origin` remote points
+at, on github.com or the Monks GitHub Enterprise (`monks.ghe.com`). Name it
+yourself if needed:
+
+```bash
+canopy repo link monks/my-tool                  # on this site's GitHub Enterprise
+canopy repo link github.com/monks/my-tool       # on github.com
+```
+
+`canopy create` scaffolds `.github/workflows/canopy-deploy.yml`, which deploys
+on every push to `main`. If you write your own workflow, it needs the
+`id-token: write` permission and nothing else:
+
+```yaml
+on:
+  push:
+    branches: [main]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      - run: npm ci
+      - run: npm exec --yes @mediamonks/canopy-cli deploy
+```
 
-Most Canopy users don't have a GitHub Enterprise seat, so they can't see or
-interact with GitHub Actions. That is why Canopy repositories are created with
-Actions turned **off**: pushing a workflow file works, but nothing runs, and
-there is no Actions tab for you to look at. Turning Actions on for a repository
-is something only a GitHub administrator can do, and you would still not see
-the runs.
+A run from any other branch, a pull request or a fork deploys nothing. Until a
+repository is linked, runs skip the deploy with a warning instead of failing.
 
-Deploy from your machine (or let your coding agent do it): run
-`canopy deploy --staging`, check the result, then `canopy promote`. It is
-usually quicker than waiting for a pipeline, and your agent can verify the
-deploy right afterwards. Run your typecheck, lint and tests locally before you
-deploy.
+Deploys from CI show up in the history under the repository and branch, e.g.
+`monks/my-tool @ main`.
 
-The rest of this page is for teams that run their own CI somewhere they can
-see it.
+A project with a Canopy repository needs no link: CI deploys from it already.
+GitHub Actions are off on Canopy repositories until a platform administrator
+turns them on for one.
+
+## Our recommendation: deploy manually
 
-Interactive `canopy login` is for humans at a terminal. For automated deploys
-(GitHub Actions, etc.) use a **deploy token**: a project-scoped credential that
-can deploy that one project and nothing else.
+Most Canopy users don't have a GitHub Enterprise seat, so they can't see the
+runs. Deploying from your machine (or letting your coding agent do it) is
+usually quicker: run `canopy deploy --staging`, check the result, then
+`canopy promote`. Run your typecheck, lint and tests locally before you deploy.
 
-## Create a token
+## A staging branch
 
-Only the project owner can create a deploy token (any editor can list
-and revoke them). From inside the project directory:
+Pushes to a second branch can deploy to the project's
+[staging channel](https://docs.canopy.website/guides/staging) only. They can never change what is live:
+no live deploy, promote or rollback.
 
 ```bash
-canopy token create --name "GitHub Actions"
+canopy repo branches --staging-ref develop
 ```
 
-This prints the token **once** — copy it immediately and store it as a CI secret
-(e.g. `CANOPY_DEPLOY_TOKEN`). It is not shown again.
+Then add the branch to the workflow's trigger so its pushes run it:
 
-Manage tokens:
+```yaml
+on:
+  push:
+    branches: [main, develop]
+```
+
+The same workflow deploys `main` live and `develop` to staging. Promote from
+staging to live by hand with `canopy promote`.
+
+## Pausing CI deploys
+
+Turn CI deploys off without unlinking or editing the workflow:
 
 ```bash
-canopy token list
-canopy token revoke <id>
+canopy repo deploys off
+canopy repo deploys on
 ```
 
-## Use it in CI
+While they are off, runs skip the deploy with a warning. The link and branches
+stay as they were. You can also flip the switch on the project's Deploys tab.
 
-The CLI picks up `CANOPY_DEPLOY_TOKEN` from the environment and uses it instead
-of an interactive login. A minimal GitHub Actions step:
+`canopy repo show` prints the repository, both branches and whether CI deploys
+are on. `canopy repo unlink` removes the link.
 
-```yaml
-- run: npm install -g @mediamonks/canopy-cli
-- run: canopy deploy
-  env:
-    CANOPY_DEPLOY_TOKEN: ${{ secrets.CANOPY_DEPLOY_TOKEN }}
+## Other CI: deploy tokens
+
+For CI that isn't GitHub Actions, or a repository you can't link, use a
+**deploy token**: a project-scoped credential that can deploy that one project
+and nothing else.
+
+Only the project owner can create one (any editor can list and revoke them).
+From inside the project directory:
+
+```bash
+canopy token create --name "Buildkite"
 ```
 
-(`canopy deploy` runs the project's `canopy.json` build command by default;
-pass `--no-build` if CI already built the output directory.)
+This prints the token **once** — store it as a CI secret right away. It is not
+shown again.
 
-No `canopy login` step is needed — the token is the credential.
+```bash
+canopy token list
+canopy token revoke <id>
+```
 
-## Notes
+Set it as `CANOPY_DEPLOY_TOKEN` in the CI environment and run `canopy deploy`.
+No `canopy login` is needed. A deploy token also works in GitHub Actions, and
+wins over the linked repository when both are there.
 
-- A deploy token can only deploy its own project — it reaches that project's
-  deploy endpoints and upload grants and nothing else. If it strays to another
-  project's resources, the platform rejects it.
-- The token belongs to the project, not to the person who created it. It keeps
-  working when they leave the project or the company; deploys it makes show up
-  in the history under the token's name.
-- A token that goes 90 days without a deploy stops working. Active pipelines
-  never notice; a forgotten one dies on its own. The token list shows when each
-  was last used.
-- Revoke a token the moment it might be exposed; create a fresh one to replace it.
+- A deploy token can only deploy its own project.
+- It belongs to the project, not to the person who created it, and keeps
+  working when they leave.
+- A token that goes 90 days without a deploy stops working.
+- Turning CI deploys off does not stop a deploy token. Revoke it for that.

package/dist/docs/cli-create.md

@@ -40,6 +40,8 @@ canopy create
 
 Walks you through name, slug, and template, registers the project, and scaffolds a ready-to-run starter with next steps printed.
 
+The starter includes `.github/workflows/canopy-deploy.yml`, which deploys on every push to `main` once the repository is linked. `create` never links a repository itself; the next steps print the exact [`canopy repo link`](https://docs.canopy.website/cli/repo) command for the folder's GitHub `origin`. See [CI deploys](https://docs.canopy.website/guides/ci).
+
 ```bash
 canopy create "Team Retro Board" --slug retro-board --template spa
 ```

package/dist/docs/cli-deploy.md

@@ -33,7 +33,7 @@ canopy deploy --project my-app ./out
 
 Deploys are versioned and immutable: nothing overwrites an old version, so [canopy rollback](https://docs.canopy.website/cli/rollback) can always take you back.
 
-**CI.** Set the `CANOPY_DEPLOY_TOKEN` environment variable to a project-scoped deploy token (from [canopy token create](https://docs.canopy.website/cli/token)) and `canopy deploy` works with no `canopy login` — the token can deploy exactly one project and nothing else. Deploys from GitHub Actions are tagged with their source in the deploy history.
+**CI.** In GitHub Actions, `canopy deploy` needs no secret and no `canopy login`: with `permissions: id-token: write` in the workflow, it proves which repository and branch the run comes from and deploys a project [linked](https://docs.canopy.website/cli/repo) to that repository. A run on the project's staging branch deploys to staging without `--staging`. An unlinked project, or one whose CI deploys are off, skips the deploy with a warning instead of failing. Elsewhere, set `CANOPY_DEPLOY_TOKEN` to a project-scoped deploy token (from [canopy token create](https://docs.canopy.website/cli/token)); it wins over the linked repository when both are there. Deploys from GitHub Actions are tagged with their source in the deploy history. See [CI deploys](https://docs.canopy.website/guides/ci).
 
 ## Examples