Skip to content

feat: report a deployment hosted elsewhere with argos deploy --url - #424

Open
gregberge wants to merge 3 commits into
mainfrom
claude/cli-external-deployment-fa3da4
Open

gregberge wants to merge 3 commits into
mainfrom
claude/cli-external-deployment-fa3da4

Conversation

@gregberge

Copy link
Copy Markdown
Member

SDK and CLI half of ARG-521. Backend: argos-ci/argos#2786 (open, not deployed yet).

What

argos deploy --url https://web-git-feature-login.vercel.app

argos deploy --url <url> reports a deployment hosted on Vercel, Netlify, Cloudflare or anywhere else. Argos links it to the builds of the same commit: the build page shows it, and each screenshot opens on the same page of that deployment. ARGOS_PREVIEW_BASE_URL did that per screenshot, so it and the previewUrl upload option are now deprecated.

  • CLI: argos deploy [directory] [--url <url>]. Pass a directory to deploy a static build on Argos (unchanged), or --url, not both. --prod, --project and --token work for both.

  • Core: deploy() takes url in place of root. The parameters are a union, so passing both is a type error (and a runtime error from plain JS). It resolves to the deployment either way.

  • API client: regenerated with url and an optional files.

  • Deprecation: @deprecated on UploadParameters.previewUrl (the Playwright, Cypress and Vitest options inherit it) and Config.previewBaseUrl, plus a warning printed once per process for each one in use:

    [Argos] ARGOS_PREVIEW_BASE_URL is deprecated. Report the deployment to Argos instead with "argos deploy --url ", and Argos links each screenshot to the same page on it. Learn more: https://argos-ci.com/docs/learn/deployments

    Both keep working exactly as before.

Choices worth a look

argos deploy --url, not a new command. The API has one endpoint where url replaces files, and everything around it is shared: commit, branch and pull request detection, --prod, --project, the token. One command keeps "a deployment" a single concept in the CLI, as it is in the API. deploy --url could read as "deploy to this URL", so the directory and --url are mutually exclusive with an explicit error, and the help text says what each does and shows both forms:

Usage: @argos-ci/cli deploy [options] [directory]

Deploy a static build (Storybook or any static site) to Argos, or report a
deployment hosted elsewhere

Options:
  --url <url>       URL of a deployment hosted elsewhere, such as a Vercel or
                    Netlify preview. Argos links it to the builds of the same
                    commit, and links each screenshot to the same page on it
  ...
  --prod            Mark the deployment as production. When omitted, Argos
                    infers the environment from the branch (default: false)

Examples:
  argos deploy ./storybook-static
  argos deploy --url https://my-app-git-feature.vercel.app

No automatic deployment when ARGOS_PREVIEW_BASE_URL is set. I considered having upload() report a deployment from the variable and chose not to:

  • Uploads run once per shard, so each shard would report its own deployment for the same commit.
  • It needs deployments:write. A token limited to builds:write would start failing uploads, or the SDK would have to swallow the error.
  • The environment is inferred from the branch, so uploads on the default branch would create production deployments from a variable called "preview".
  • A project that already deploys its Storybook on Argos would get a second deployment for the same commit.
  • The function form of previewUrl can rewrite paths, which a deployment can't express.
  • Uploading screenshots would gain a side effect nobody asked for, one that fails until #2786 is deployed.

So the variable keeps working as it does today, and the warning points to the one-line replacement.

API client generated from the PR's spec. build-schema-types reads the production spec, which lacks url until #2786 ships. I generated it from that branch's backend build (generate-openapi.js at 890adddbd). The diff against the committed schema (argos main) is only #2786's change: files optional, url added, the operation description.

deploy({ url }) reads the deployment back. For an external deployment, POST /deployments answers { deploymentId, uploadFiles: [] }. deploy() then calls GET /deployments/{id} (same deployments:write permission) so it resolves to the same shape as a finalized Argos deployment, with the URL as Argos normalized it. That costs one extra request.

The CLI checks --url loosely. Only that it is an http or https URL, so a missing scheme (my-app.vercel.app) fails before any request, with the fix in the message. The API stays the source of truth for the rest.

Merge and release

Merge and release once argos#2786 is deployed. Until then the API answers 400 to a url (it requires files), so argos deploy --url would fail. Nothing changes for existing users. The docs are written in a separate argos-ci/docs PR.

Testing

  • Core deploy.test.ts: the url request carries no files, nothing is finalized, and the deployment read back is returned; pull request, head commit and environment are sent; root and url together are rejected before any request.
  • Core preview-url.test.ts and upload.test.ts: formatting, one warning per source per process, the option taking precedence, and ARGOS_PREVIEW_BASE_URL still setting previewUrl on screenshots while warning.
  • CLI deploy.test.ts: directory, url, both, neither, invalid URLs. New e2e: argos deploy with no argument exits 1 with the error (no API call).
  • Ran the built CLI against a local stand-in for the #2786 endpoint: argos deploy --url … --prod sent { commit, branch, environment: "production", url } without files and printed ✔ Deployment reported: https://web-git-feature-login.vercel.app/. argos upload with ARGOS_PREVIEW_BASE_URL set printed the warning once.
  • check-types, lint, check-format and unit tests pass for api-client, core, cli, playwright, cypress and vitest.
  • Not run against the real API, which isn't deployed. There is no live e2e for --url yet because CI's e2e runs against production; it is worth adding once #2786 ships.

🤖 Generated with Claude Code

gregberge and others added 3 commits November 16, 2026 21:23
Regenerated from the spec of argos-ci/argos#2786, which is not deployed
yet. With it, `POST /v2/deployments` takes a `url` in place of `files`
to report a deployment hosted elsewhere. The diff against argos main is
only that change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`argos deploy --url <url>` tells Argos where a commit is deployed on
Vercel, Netlify or any other host. Argos links the deployment to the
builds of the same commit and opens each screenshot on it. The directory
argument becomes optional: pass a directory to deploy a static build on
Argos, or `--url`, not both.

In `@argos-ci/core`, `deploy()` takes `url` in place of `root` and
resolves to the deployment either way. Both reuse the same CI detection
for the commit, branch, pull request and head commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ption

Reporting a deployment with `argos deploy --url` gives Argos what both
did, once per commit instead of per screenshot. They keep working, but
are marked `@deprecated` and print a warning once per process that
points to `argos deploy --url`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gregberge
gregberge requested a review from jsfez November 16, 2026 20:37

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant