Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions packages/api-client/src/schema.ts
Original file line number Diff line number Diff line change
Expand Up @@ -543,7 +543,13 @@ export interface paths {
put?: never;
/**
* Create a deployment
* @description Create a deployment and receive signed upload URLs for the files Argos doesn't already store. Files already present (matched by content hash) are reused and omitted from `uploadFiles`. The environment is inferred from the branch when omitted.
* @description Create a deployment hosted by Argos, or report one hosted elsewhere.
*
* With `files`, Argos returns signed upload URLs for the files it doesn't already store. Files already present (matched by content hash) are reused and omitted from `uploadFiles`. Finalize the deployment once they are uploaded.
*
* With `url`, the deployment is ready at once and `uploadFiles` is empty.
*
* The environment is inferred from the branch when omitted.
*/
post: operations["createDeployment"];
delete?: never;
Expand Down Expand Up @@ -5603,13 +5609,18 @@ export interface operations {
* @enum {string}
*/
environment?: "preview" | "production";
/** @description List of files to deploy */
files: {
/** @description The files Argos hosts and serves. Required unless `url` is set. */
files?: {
path: string;
hash: components["schemas"]["Sha256Hash"];
size: number;
contentType: string;
}[];
/**
* Format: uri
* @description The URL of a deployment hosted elsewhere, such as a Vercel or Netlify preview. The deployment is created `ready`, and the builds of the same commit link their screenshots to it. Required unless `files` is set.
*/
url?: string;
};
};
};
Expand Down
13 changes: 12 additions & 1 deletion packages/cli/e2e/deploy.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { expect, test } from "vitest";

import { getRequiredEnv, run } from "./utils";
import { getRequiredEnv, run, type CommandError } from "./utils";

getRequiredEnv("ARGOS_TOKEN");

Expand All @@ -13,3 +13,14 @@ test("deploys a static site with HTML and CSS assets", () => {
expect(deployResult.combined).toContain("Deployed:");
expect(deployResult.combined).toMatch(/https?:\/\/\S+/);
});

test("asks for a directory or --url when both are missing", () => {
let error: CommandError | undefined;
try {
run(["deploy"]);
} catch (err) {
error = err as CommandError;
}
expect(error?.status).toBe(1);
expect(error?.stderr).toContain("Error: Missing directory or --url.");
});
53 changes: 53 additions & 0 deletions packages/cli/src/commands/deploy.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
import { resolve } from "node:path";
import { describe, expect, it } from "vitest";
import { CliError } from "../lib/cli-error";
import { getDeploySource } from "./deploy";

describe("getDeploySource", () => {
it("deploys a directory on Argos", () => {
expect(getDeploySource("storybook-static", undefined)).toEqual({
root: resolve("storybook-static"),
});
});

it("reports a deployment hosted elsewhere", () => {
expect(
getDeploySource(undefined, "https://web-git-feature.vercel.app"),
).toEqual({ url: "https://web-git-feature.vercel.app" });
});

it("accepts an http URL", () => {
expect(getDeploySource(undefined, "http://preview.internal")).toEqual({
url: "http://preview.internal",
});
});

it("refuses a directory and --url together", () => {
expect(() =>
getDeploySource("storybook-static", "https://web.vercel.app"),
).toThrow(
new CliError(
"Pass a directory or --url, not both. A directory deploys a static build on Argos; --url reports a deployment hosted elsewhere.",
),
);
});

it("asks for a directory or --url when both are missing", () => {
expect(() => getDeploySource(undefined, undefined)).toThrow(
new CliError(
"Missing directory or --url. Pass a directory to deploy a static build on Argos, or --url to report a deployment hosted elsewhere.",
),
);
});

it.each(["web-git-feature.vercel.app", "ftp://files.example.com", ""])(
"refuses %j as a URL",
(url) => {
expect(() => getDeploySource(undefined, url)).toThrow(
new CliError(
`Invalid --url value: "${url}". Use the full URL of the deployment, starting with https:// or http://.`,
),
);
},
);
});
95 changes: 87 additions & 8 deletions packages/cli/src/commands/deploy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ import type { Command } from "commander";
import { Option } from "commander";
import { deploy } from "@argos-ci/core";
import ora from "ora";
import { fail } from "../lib/cli-error";
import { handleCliError } from "../lib/run";
import {
projectOption,
tokenOption,
Expand All @@ -13,33 +15,110 @@ import {
type DeployOptions = TokenOption &
ProjectOption & {
prod?: boolean;
url?: string | undefined;
};

/** What `argos deploy` sends to Argos: files to host, or where it is hosted. */
export type DeploySource = { root: string } | { url: string };

/**
* Resolve the `[directory]` argument and `--url` option into what to deploy,
* or abort: exactly one of them is required.
*/
export function getDeploySource(
directory: string | undefined,
url: string | undefined,
): DeploySource {
if (directory !== undefined && url !== undefined) {
fail(
"Pass a directory or --url, not both. A directory deploys a static build on Argos; --url reports a deployment hosted elsewhere.",
);
}
if (url !== undefined) {
if (!isHttpUrl(url)) {
fail(
`Invalid --url value: "${url}". Use the full URL of the deployment, starting with https:// or http://.`,
);
}
return { url };
}
if (directory === undefined) {
fail(
"Missing directory or --url. Pass a directory to deploy a static build on Argos, or --url to report a deployment hosted elsewhere.",
);
}
return { root: resolve(directory) };
}

function isHttpUrl(value: string): boolean {
try {
const { protocol } = new URL(value);
return protocol === "https:" || protocol === "http:";
} catch {
return false;
}
}

export function deployCommand(program: Command) {
program
.command("deploy")
.argument("<directory>", "Directory of the static build to deploy")
.argument("[directory]", "Directory of the static build to deploy on Argos")
.description(
"Deploy a static build (Storybook or any static site) to Argos",
"Deploy a static build (Storybook or any static site) to Argos, or report a deployment hosted elsewhere",
)
.addOption(
new Option(
"--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",
),
)
.addOption(tokenOption)
.addOption(projectOption)
.addOption(
new Option("--prod", "Deploy as a production deployment").default(false),
new Option(
"--prod",
"Mark the deployment as production. When omitted, Argos infers the environment from the branch",
).default(false),
)
.addHelpText(
"after",
[
"",
"Examples:",
" argos deploy ./storybook-static",
" argos deploy --url https://my-app-git-feature.vercel.app",
].join("\n"),
)
.action(async (directory: string, options: DeployOptions) => {
const spinner = ora("Deploying").start();
.action(async (directory: string | undefined, options: DeployOptions) => {
let source: DeploySource;
try {
source = getDeploySource(directory, options.url);
} catch (error) {
handleCliError(error);
}
const isExternal = "url" in source;
const spinner = ora(
isExternal ? "Reporting deployment" : "Deploying",
).start();
try {
const result = await deploy({
token: options.token,
project: options.project,
root: resolve(directory),
environment: options.prod ? "production" : undefined,
...source,
});
spinner.succeed(`Deployed: ${result.url}`);
spinner.succeed(
isExternal
? `Deployment reported: ${result.url}`
: `Deployed: ${result.url}`,
);
} catch (error) {
if (error instanceof Error) {
spinner.fail(`Deploy failed: ${error.message}`);
spinner.fail(
isExternal
? `Could not report the deployment: ${error.message}`
: `Deploy failed: ${error.message}`,
);
console.error(error.stack);
}
process.exit(1);
Expand Down
4 changes: 4 additions & 0 deletions packages/core/src/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -419,6 +419,10 @@ export interface Config {
/**
* Base URL to use for preview links.
* @example "https://my-preview.example.com"
* @deprecated `ARGOS_PREVIEW_BASE_URL` is deprecated. Report the deployment
* to Argos instead, with `argos deploy --url <url>` or `deploy({ url })`.
* Argos links each screenshot to the same page on it.
* @see https://argos-ci.com/docs/learn/deployments
*/
previewBaseUrl: string | null;

Expand Down
97 changes: 97 additions & 0 deletions packages/core/src/deploy.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -91,4 +91,101 @@ describe("#deploy", () => {
expect(bodies).toHaveLength(1);
expect(bodies[0]).not.toHaveProperty("project");
});

describe("with a url", () => {
const url = "https://web-git-feature.vercel.app";
const deployment = {
id: "43",
status: "ready",
environment: "preview",
branch: "feature",
commitSha: commit,
url: `${url}/`,
createdAt: "2026-11-16T12:00:00.000Z",
};

/**
* Answers the requests `deploy` makes to report a deployment hosted
* elsewhere, and collects them.
*/
function captureReportRequests() {
const received = { bodies: [] as unknown[], finalized: false };
server.use(
http.post(`${apiBaseUrl}/deployments`, async ({ request }) => {
received.bodies.push(await request.json());
return HttpResponse.json(
{ deploymentId: "43", uploadFiles: [] },
{ status: 201 },
);
}),
http.get(`${apiBaseUrl}/deployments/43`, () =>
HttpResponse.json(deployment),
),
http.post(`${apiBaseUrl}/deployments/43/finalize`, () => {
received.finalized = true;
return HttpResponse.json(deployment);
}),
);
return received;
}

it("reports the deployment without files and returns it", async () => {
const received = captureReportRequests();

const result = await deploy({
url,
apiBaseUrl,
commit,
branch: "feature",
token: "92d832e0d22ab113c8979d73a87a11130eaa24a9",
});

expect(received.bodies).toEqual([
expect.objectContaining({ commit, branch: "feature", url }),
]);
expect(received.bodies[0]).not.toHaveProperty("files");
expect(received.finalized).toBe(false);
expect(result).toEqual(deployment);
});

it("sends the pull request and the environment", async () => {
vi.stubEnv("ARGOS_PR_NUMBER", "12");
vi.stubEnv("ARGOS_PR_HEAD_COMMIT", prHeadCommit);
const received = captureReportRequests();

await deploy({
url,
environment: "production",
apiBaseUrl,
commit,
branch: "feature",
token: "92d832e0d22ab113c8979d73a87a11130eaa24a9",
});

expect(received.bodies).toEqual([
expect.objectContaining({
url,
prNumber: 12,
prHeadCommit,
environment: "production",
}),
]);
});

it("refuses a root and a url together", async () => {
const received = captureReportRequests();

await expect(
deploy({
url,
root: join(__dirname, "../../../__fixtures__/deploy"),
apiBaseUrl,
commit,
branch: "feature",
token: "92d832e0d22ab113c8979d73a87a11130eaa24a9",
} as unknown as Parameters<typeof deploy>[0]),
).rejects.toThrow("`root` and `url` can't be used together.");
expect(received.bodies).toEqual([]);
});
});
});
Loading
Loading