Deploy from CI

Every merge
ships the site.

Give your pipeline a deploy token and it can publish a built folder to arcdoq with no browser and nobody signed in. Point Claude at this page and it will write the workflow for you. The one step that stays yours is pasting the token into your repository secrets.

Works with GitHub Actions or any CI On the Pro plan

01 Create a token

One credential, shown once.

In the app, open Tokens and choose New token. Name it after the thing that will use it, so a list of them stays readable later. You need to be an admin or owner of the workspace.

Shown once Only a hash is stored, so the token cannot be looked up, recovered, or re-sent afterwards. Copy it before you close the panel. If you lose it, revoke it and make another.

Owned by the workspace The token belongs to the workspace, not to you, so it keeps working after the person who created it leaves. Revoking it in the app is the only way to stop it.

Publishes anywhere in the workspace A deploy token can publish to any site in the workspace. Treat it like a password, and give each pipeline its own so you can revoke one without breaking the rest.

02 Store it

As a secret, never in a file.

On GitHub: Settings, Secrets and variables, Actions, New repository secret. Name it ARCDOQ_DEPLOY_TOKEN. Any CI with a secret store works the same way.

repository secret

ARCDOQ_DEPLOY_TOKEN=arcdoq_deploy_<id>_<secret>

Tokens start with arcdoq_deploy_ on purpose: the prefix is distinctive enough for a secret scanner to catch if one ever lands in a commit. If that happens, revoke it in the app. Rotating is cheap; a live credential in git history is not.

03 Wire it up

Hand this page to Claude.

A deploy is one request: your built folder as a list of files. Rather than copying a script you have to understand, give Claude this page and the two facts it cannot guess, your slug and your build directory. It writes the workflow, and stops at the secret, which is yours to paste.

prompt

Read https://arcdoq.com/docs/deploy and set up arcdoq deploys for this repo.
The site slug is "docs", my built output is in ./dist, and the site should be
private.

Do not put the token in any file. Tell me to add ARCDOQ_DEPLOY_TOKEN to the
repository secrets myself.

Writing it by hand instead? Everything the workflow needs is below. Build, walk the output directory, and send one request.

04 The request

One POST, one folder.

Text files go as utf8. Anything binary, an image or a font, goes as base64 with encoding set. Paths are relative to your build directory, and a root index.html is required.

The first deploy to a new slug must say visibility, and arcdoq will not guess. A site published from CI has nobody watching it, and the two wrong guesses are not equally bad: wrongly private is noticed in seconds, wrongly public may never be. Later deploys leave it out and inherit whatever the site already is.

POST https://mcp.arcdoq.com/deploy

Authorization: Bearer $ARCDOQ_DEPLOY_TOKEN
Content-Type: application/json

{
  "site": "docs",
  "visibility": "private",        // required on the FIRST deploy only
  "files": [
    { "path": "index.html", "content": "<!doctype html>..." },
    { "path": "assets/app.css", "content": "body{...}" },
    { "path": "assets/logo.png", "content": "iVBORw0KGgo...", "encoding": "base64" }
  ]
}

200 response

{
  "success": true,
  "created": false,
  "slug": "docs",
  "visibility": "private",
  "url": "https://orbitalx.sites.arcdoq.com/docs",
  "serving": "live",
  "message": "Published 43 files to docs."
}

05 The contract

What the endpoint answers.

POST https://mcp.arcdoq.com/deploy with a bearer token. The site is keyed by slug, not by an id, so the same three lines of config resolve to the same site forever and your pipeline keeps no state. If the slug does not exist yet, the deploy creates it.

Published is not reachable The response carries serving: live means it answers now, provisioning means give it a moment, and failed means it did not come up. Do not print "deployed" on provisioning. Exit non-zero only on failed.

Renaming breaks the link The slug is the link. Rename the site in the app and the next deploy creates a new one under the old slug. It is visible and recoverable, but worth knowing before you rename a site your pipeline owns.

It will not clobber an AI-built site Deploying to a slug that belongs to a site built with the AI builder is refused with 409, rather than replacing what the builder made. Deploy to a different slug.

06 When it does not work

401 The token is wrong, revoked, or expired. Every one of those answers the same way on purpose, so the response cannot be used to work out which tokens exist. Check the secret is set on the job, then check the token is still active in the app.

422 Usually the first deploy to a new slug with no visibility. Say "public" or "private" once; every deploy after that inherits it. Also covers a fileset with no root index.html.

402 The workspace is on Free. Publishing by hand stays free, from the app or from Claude; deploying from CI is on Pro. Existing tokens keep listing and revoking on Free, they just stop publishing.

413 The upload is over the plan's size cap. The whole folder goes up in one request today, so media-heavy sites are the usual cause. Trim what ships, or move large assets out of the build.

429 Too many deploys in an hour from one token. The limit is per token, not per workspace, so one busy pipeline cannot spend everyone else's budget. Wait, then retry.