Document deployments (#204)

Author: gregberge

docs/introduction.mdx

@@ -9,8 +9,6 @@ import { HelpSection } from "@site/src/partials";
 import CypressLogo from "@site/src/img/frameworks/cypress.png";
 import PlaywrightLogo from "@site/src/img/frameworks/playwright.png";
 import PuppeteerLogo from "@site/src/img/frameworks/puppeteer.png";
-import NextjsLogo from "@site/src/img/frameworks/next-js.png";
-import ReactRouterLogo from "@site/src/img/frameworks/react-router.png";
 import WebdriverIOLogo from "@site/src/img/frameworks/webdriverio.png";
 import StorybookLogo from "@site/src/img/frameworks/storybook.png";
 import OthersLogo from "@site/src/img/frameworks/others.png";
@@ -55,12 +53,6 @@ Learn how to setup Argos in your project:
     text="Puppeteer Quickstart"
     to="/quickstart/puppeteer"
   />
-  <XCard logo={NextjsLogo} text="Next.js Quickstart" to="/quickstart/next-js" />
-  <XCard
-    logo={ReactRouterLogo}
-    text="React Router Quickstart"
-    to="/quickstart/react-router"
-  />
   <XCard
     logo={OthersLogo}
     text="Any E2E Quickstart"
@@ -74,6 +66,7 @@ Dig deeper into Argos topics:
 
 <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 flex-wrap">
   <XCard text="Baselines & monitoring" to="/baseline-build" />
+  <XCard text="Deployments" to="/deployments" />
   <XCard text="Integrations" to="/integrations" />
   <XCard text="Flaky test detection" to="/flaky-test-detection" />
 </div>

docs/learn/deployments/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Deployments",
+  "position": 3
+}

docs/learn/deployments/auth-setting.png

@@ -0,0 +1,67 @@
+---
+slug: /deployments/authentication
+sidebar_label: Access protection
+sidebar_position: 4
+description: Restrict who can access your deployment URLs by requiring viewers to sign in with Argos.
+---
+
+# Access protection
+
+By default, deployment URLs are reachable by anyone who has the link. For most internal projects, that's not what you want—a Storybook can leak unreleased designs, copy, or features. Argos lets you require viewers to sign in with an Argos account before opening any deployment URL.
+
+Access protection is configured per project, and applies to every deployment under it.
+
+## Protection modes
+
+Argos supports three modes:
+
+| Mode                    | Preview URLs      | Production domain | Available on |
+| :---------------------- | :---------------- | :---------------- | :----------- |
+| **Public**              | No login required | No login required | All plans    |
+| **Standard protection** | Login required    | No login required | All plans    |
+| **All deployments**     | Login required    | Login required    | Team plans   |
+
+When login is required, only Argos users who have access to the project can open the deployment. Everyone else sees the Argos sign-in screen.
+
+### Public
+
+Everyone with the link can open the deployment. Use this if your project is fully public (for example, an open-source design system) or if the build is intentionally meant to be shared.
+
+### Standard protection
+
+Login required for every URL **except** the production domain. The production domain stays public; all preview URLs and the immutable deployment URLs require sign-in.
+
+This is the right default for most teams: production is browsable by anyone (designers, customers, stakeholders), while previews stay private to your team.
+
+### All deployments
+
+Login required for **all** URLs, including the production domain. Use this when the production build itself contains sensitive material—for example, internal tools or a Storybook for unreleased features.
+
+This option requires a Team plan.
+
+## Configure access protection
+
+1. Open your project in Argos.
+2. Go to **Settings → Deployments**.
+3. Toggle **Log in protection** and pick the level.
+
+![Deployment authentication setting](./auth-setting.png)
+_Project Settings → Deployments → Deployment authentication._
+
+Changes take effect immediately on the next request.
+
+## Who can access protected deployments
+
+When login protection is enabled, a viewer must:
+
+1. Be signed in to Argos.
+2. Have access to the project the deployment belongs to.
+
+Project access follows the [team roles and permissions](/team-members-and-roles) rules: team members, contributors invited to the project, and account owners.
+
+A viewer who does not have access sees a 404-style screen rather than a sign-in prompt, so the existence of the project is not disclosed.
+
+## Related
+
+- [Deployments overview](/deployments)
+- [URLs and domains](/deployments/urls)

docs/learn/deployments/authentication.mdx

@@ -0,0 +1,113 @@
+---
+slug: /deployments/ci
+sidebar_label: Use in CI
+sidebar_position: 5
+description: Deploy a Storybook (or any static build) to Argos automatically on every pull request from GitHub Actions.
+---
+
+import { RunPkgCommand } from "@site/src/partials";
+
+# Use deployments in CI
+
+Running `argos deploy` from CI is the most common setup: a new deployment is created on every push to a pull request, and the deployment link appears in the PR comment alongside Argos visual tests.
+
+This page walks through a GitHub Actions setup for Storybook. The same pattern works for any static build and any CI provider.
+
+## Prerequisites
+
+- A static build step that produces a directory (for Storybook: `npm run build-storybook` → `storybook-static/`).
+- An `ARGOS_TOKEN` available as a CI secret. You can also use [GitHub OIDC](/github-oidc) or [tokenless authentication](/github-tokenless) to avoid managing a secret.
+
+## GitHub Actions example
+
+```yaml title=".github/workflows/argos-deploy.yml"
+name: Deploy Storybook to Argos
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+      - run: npm ci
+      - run: npm run build-storybook
+      - run: npx --no-install argos deploy ./storybook-static
+        env:
+          ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
+```
+
+A few notes:
+
+- The workflow listens to both `pull_request` and `push` to `main`. Pull request runs produce **preview** deployments; pushes to `main` produce **production** deployments (because `main` matches the default production branch pattern—see [Environments](/deployments/environments)).
+- `actions/checkout` gives Argos the commit SHA and branch it needs to associate the deployment with the right pull request.
+- The `ARGOS_TOKEN` is the project token from **Settings → General → Token**.
+
+## Force a production deployment
+
+If your production branch differs from your repository's default branch (or if you want to be explicit), pass the `--prod` flag:
+
+```yaml
+- run: npx --no-install argos deploy ./storybook-static --prod
+  env:
+    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
+```
+
+You can keep the same workflow for both preview and production by branching on the event:
+
+```yaml
+- name: Deploy
+  run: |
+    if [ "${{ github.event_name }}" = "push" ]; then
+      npx --no-install argos deploy ./storybook-static --prod
+    else
+      npx --no-install argos deploy ./storybook-static
+    fi
+  env:
+    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
+```
+
+## Combine with visual testing
+
+The `deploy` and `upload` commands are independent: you can run both in the same workflow to get a deployment URL **and** Argos visual tests on the same commit.
+
+```yaml
+- run: npm run build-storybook
+- run: npm run test:visual # Your usual Argos visual test job
+  env:
+    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
+- run: npx --no-install argos deploy ./storybook-static
+  env:
+    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
+```
+
+Argos posts a single pull request comment that lists both the deployment URLs and the visual build results.
+
+![Pull request comment with deployment and visual build rows](./pr-comment.png)
+_GitHub pull request comment showing both the deployment and the Argos visual build._
+
+## Status checks
+
+Each deployment registers a commit status named `argos-deploy/<project>`. The status starts as **pending** when the upload begins and becomes **success** when the deployment is ready. You can require it in your branch protection rules if a missing deployment should block a merge.
+
+## Other CI providers
+
+The `argos deploy` command has no GitHub-specific behavior. To run it on another CI provider:
+
+1. Build your static directory in your pipeline.
+2. Set `ARGOS_TOKEN` as a secret.
+3. Run `argos deploy <directory>` (add `--prod` for production).
+
+Argos automatically detects the commit SHA, branch, and pull request number from the most common CI environment variables.
+
+## Related
+
+- [Deployments overview](/deployments)
+- [Environments](/deployments/environments)
+- [GitHub integration](/github)
+- [Argos CLI reference](/argos-cli)

docs/learn/deployments/ci.mdx

@@ -0,0 +1,95 @@
+---
+slug: /deployments/environments
+sidebar_label: Environments
+sidebar_position: 2
+description: Argos provides two deployment environments—preview and production—each with its own URLs and access rules.
+---
+
+import { RunPkgCommand } from "@site/src/partials";
+
+# Environments
+
+Every deployment is created in one of two environments:
+
+- **Preview** — A non-production deployment, typically created from a feature branch or pull request. Each preview gets its own URL and never replaces the production deployment.
+- **Production** — The deployment served on your project's production domain. Only deployments from a production branch are promoted here.
+
+The environment is decided when the deployment is created and cannot be changed afterwards.
+
+## How the environment is determined
+
+Argos picks the environment in this order:
+
+1. **Explicit override.** If you pass `--prod` to the CLI (or `environment: "production"` to the SDK), the deployment is created as production.
+2. **Branch match.** Otherwise, the branch name is matched against the project's **production branch pattern**. A match → production. No match → preview.
+
+By default, the production branch pattern follows your Git repository's default branch (usually `main`). You can override it from project settings.
+
+## Preview deployments
+
+Preview deployments are the default. They are created when:
+
+- You run `argos deploy <directory>` without `--prod`, **and**
+- The branch does not match the production branch pattern.
+
+Each preview deployment gets:
+
+- A unique, immutable **deployment URL** — always points to that exact build.
+- A **branch URL** — always points to the latest preview on that branch. Useful to share a link that follows a feature branch as it evolves.
+
+See [URLs and domains](/deployments/urls) for the full list of URLs Argos generates.
+
+When a preview deployment is linked to a pull request, the deployment status appears in the [pull request comment](/pull-request-comments) and as a commit status check on the PR.
+
+## Production deployments
+
+A production deployment is created when:
+
+- You run `argos deploy <directory> --prod`, **or**
+- The branch matches the production branch pattern.
+
+When a new production deployment becomes ready, it is **promoted**: the project's production domain immediately starts serving the new build. Earlier production deployments remain available at their own URLs.
+
+The Argos dashboard shows a **Current** badge next to the deployment that is currently serving the production domain.
+
+![Current production deployment badge](./current-badge.png)
+_The deployments list highlights the deployment currently promoted to production._
+
+## Configure the production branch
+
+By default, Argos uses your Git repository's default branch as the production branch. You can customize this from **Settings → Deployments → Production deployment branch**.
+
+![Production deployment branch setting](./prod-branch.png)
+_Project Settings → Deployments → Production deployment branch._
+
+To customize:
+
+1. Disable **Use GitHub repository's default branch**.
+2. Enter a [glob pattern](https://github.com/isaacs/minimatch) that matches your production branches.
+
+Examples:
+
+- `main` — Only the `main` branch.
+- `{main,production}` — Either `main` or `production`.
+- `release/**` — Any branch under `release/` (for example `release/2024-q4`).
+
+Any branch matching the pattern produces a production deployment on the next CLI run, even without `--prod`.
+
+## Forcing an environment from the CLI
+
+You can force the environment regardless of the branch with the `--prod` flag:
+
+<RunPkgCommand command="argos deploy ./storybook-static --prod" />
+
+This is useful when you want to:
+
+- Deploy a one-off production build from a local machine.
+- Promote a deployment from a non-standard branch (for example, a release branch that doesn't match the configured pattern).
+
+There is currently no flag to force a preview from a production branch—simply do not pass `--prod` and adjust the production branch pattern if needed.
+
+## Related
+
+- [Deployments overview](/deployments)
+- [URLs and domains](/deployments/urls)
+- [Use deployments in CI](/deployments/ci)

docs/learn/deployments/current-badge.png

@@ -0,0 +1,86 @@
+---
+slug: /deployments
+sidebar_label: Overview
+sidebar_position: 1
+description: Deploy static builds like Storybook to Argos on every pull request and review them on a live URL.
+---
+
+import { RunPkgCommand } from "@site/src/partials";
+
+# Deployments
+
+A **deployment** on Argos is a static build—most commonly a Storybook—served on a unique URL that you can open, share, and review. Every time you run the Argos CLI, Argos uploads your build, generates a URL, and posts the status back to your pull request.
+
+Use deployments to:
+
+- Preview a Storybook for every pull request, with no infrastructure of your own to maintain.
+- Share a live link with designers, product, or stakeholders to review work in context.
+- Browse the history of every deployed build across branches and commits.
+
+![Deployments list in the Argos dashboard](./deployments-list.png)
+_Deployments list in the Argos dashboard._
+
+## How it works
+
+A deployment is created in three phases:
+
+1. **Build** — The Argos CLI scans your local directory and computes a content hash for every file.
+2. **Upload** — Argos returns pre-signed upload URLs for the files it doesn't already have. Files that match an existing hash are skipped, so re-deploying an unchanged build is near-instant.
+3. **Serve** — Once the upload finishes, Argos finalizes the deployment, assigns it a URL, and reports the status to your Git provider.
+
+Each deployment is **immutable**. Re-running the deploy command always produces a new deployment with its own URL—the previous one keeps working.
+
+## Quickstart
+
+The following steps get a Storybook deployed in under a minute. The same flow works for any static directory (Vite build, Next.js export, plain HTML, etc.).
+
+### 1. Install the Argos CLI
+
+<RunPkgCommand command="npm install --save-dev @argos-ci/cli" />
+
+### 2. Build your static site
+
+Generate the directory you want to deploy. For Storybook:
+
+```bash
+npm run build-storybook
+```
+
+This produces a `storybook-static/` directory.
+
+### 3. Deploy
+
+<RunPkgCommand command="argos deploy ./storybook-static" />
+
+The CLI uploads your build and prints a unique URL when the deployment is ready:
+
+```
+✔ Deployed: https://my-project-abcd123-acme.argos-ci.live
+```
+
+By default, the deployment is created in the **preview** environment. To deploy to **production**, add the `--prod` flag:
+
+<RunPkgCommand command="argos deploy ./storybook-static --prod" />
+
+See [Environments](/deployments/environments) for the rules that decide which environment a deployment lands in.
+
+## Authentication
+
+The deploy command uses the same authentication as the rest of the Argos CLI. Set the `ARGOS_TOKEN` environment variable in CI:
+
+```bash
+ARGOS_TOKEN=<your-project-token>
+```
+
+You can find the project token in **Settings → General → Token**. On GitHub Actions, you can also use [OIDC](/github-oidc) or [tokenless authentication](/github-tokenless) to avoid managing a secret.
+
+## What's next
+
+<div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+
+- [**Environments**](/deployments/environments) — How preview and production deployments are determined, and how to customize the production branch.
+- [**URLs and domains**](/deployments/urls) — The URLs Argos generates for each deployment, and how to set the production domain.
+- [**Access protection**](/deployments/authentication) — Restrict who can open deployment URLs.
+- [**Use in CI**](/deployments/ci) — Deploy automatically on every pull request with GitHub Actions.
+
+</div>