From 3d53de55d49825e614477cbc9d86bbd725f23cde Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Greg=20Berg=C3=A9?= Date: Thu, 5 Nov 2026 11:58:41 +0100 Subject: [PATCH 1/3] docs(tokens): several project tokens per project, shown once MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Projects can now have several tokens, each with a name, linked projects, permissions, an expiration and a last-used date. Tokens are hashed and shown only once, so the docs no longer say to copy the token from the project settings or to regenerate it. - Add Account & access → Project tokens: where tokens are managed and by whom, permission presets, expiration, rotation without downtime, multi-project tokens and ARGOS_PROJECT, legacy tokens, and the API/MCP endpoints. - Point every "Settings → Authentication → Project token" mention to creating a token, and replace the Regenerate section of Run Argos in CI. - Say which permissions the CLI read commands, baseline download and media commands need, and that a multi-project token needs ARGOS_PROJECT. - Transfer: tokens linked only to the project move with it. Co-Authored-By: Claude Opus 5.5 --- api-reference/README.md | 4 +- docs/SUMMARY.md | 1 + docs/agents/mcp-server.md | 5 +- docs/learn/account-and-access/README.md | 1 + .../account-and-access/account-management.md | 4 +- .../account-and-access/project-tokens.md | 177 ++++++++++++++++++ .../security-and-compliance.md | 2 +- .../how-to-subscribe.md | 2 + docs/learn/deployments/README.md | 2 +- .../deployments/use-deployments-in-ci.md | 2 +- .../ci-pipelines/run-argos-in-ci.md | 13 +- .../migrate-to-argos/from-applitools.md | 2 +- .../migrate-to-argos/from-backstopjs.md | 2 +- .../migrate-to-argos/from-chromatic.md | 2 +- .../migrate-to-argos/from-lost-pixel.md | 2 +- .../migrate-to-argos/from-percy.md | 4 +- .../from-playwright-native-screenshots.md | 2 +- .../from-vitest-native-screenshots.md | 2 +- .../github-actions-authentication.md | 2 +- docs/learn/integrations/github-integration.md | 2 +- docs/learn/media/standalone-media-upload.md | 12 +- .../fix-flaky-tests-with-ai-agents.md | 2 +- .../review-builds-with-ai-agents.md | 4 +- docs/quickstart/any-test-framework.md | 2 +- docs/quickstart/cypress-quickstart.md | 2 +- docs/quickstart/playwright-quickstart.md | 2 +- docs/quickstart/puppeteer-quickstart.md | 2 +- .../quickstart/storybook-quickstart/README.md | 2 +- ...torybook-legacy-less-than-v8-quickstart.md | 2 +- .../storybook-test-runner-quickstart.md | 2 +- docs/quickstart/vitest-quickstart.md | 2 +- docs/quickstart/webdriverio-quickstart.md | 2 +- .../argos-command-line-interface-cli.md | 10 +- 33 files changed, 230 insertions(+), 49 deletions(-) create mode 100644 docs/learn/account-and-access/project-tokens.md diff --git a/api-reference/README.md b/api-reference/README.md index dddedf7e..1d04d641 100644 --- a/api-reference/README.md +++ b/api-reference/README.md @@ -31,10 +31,10 @@ The Argos API authenticates requests with a **bearer token**. Add an `Authorizat Authorization: Bearer ``` -In most cases this is a **project token**, which you can find in your project settings on [argos-ci.com](https://argos-ci.com). A project token grants access to a single project, so it's safe to use in your CI environment. +In most cases this is a **project token**. Create one in your project's **Settings → Authentication** on [argos-ci.com](https://app.argos-ci.com), or in **Team Settings → Tokens** for a token linked to several projects. Argos shows it only once: copy it when you create it. A project token only reaches the projects it is linked to, and only the endpoints its permissions cover, so it's safe to use in your CI environment. See [Project tokens](https://argos-ci.com/docs/learn/account-and-access/project-tokens) for permissions, expiration, and rotation. {% hint style="warning" %} -Your token carries the ability to create and update builds in your project. Keep it secret: store it as a CI secret or environment variable, and never commit it to version control or expose it in client-side code. +Your token can create and update builds in your project, depending on its permissions. Keep it secret: store it as a CI secret or environment variable, and never commit it to version control or expose it in client-side code. {% endhint %} Some endpoints act on behalf of a user rather than a project — for example, submitting a review, posting a comment, or resolving a thread. These require a **personal access token**, which is attributed to your Argos user and checked against your project permissions. You can create one in your personal settings on [argos-ci.com](https://argos-ci.com). diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index db186aef..5e1ab9b8 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -87,6 +87,7 @@ * [Account management](learn/account-and-access/account-management.md) * [Analytics](learn/account-and-access/analytics.md) * [Team members & roles](learn/account-and-access/team-members-and-roles.md) + * [Project tokens](learn/account-and-access/project-tokens.md) * [Passkeys](learn/account-and-access/passkeys.md) * [GitHub single sign-on](learn/account-and-access/github-single-sign-on.md) * [SAML single sign-on](learn/account-and-access/saml-single-sign-on.md) diff --git a/docs/agents/mcp-server.md b/docs/agents/mcp-server.md index 165253ea..e191cf73 100644 --- a/docs/agents/mcp-server.md +++ b/docs/agents/mcp-server.md @@ -25,6 +25,7 @@ It integrates with popular AI assistants like Claude, enabling them to: - Read and post comments on builds and tests - Investigate flaky tests and ignore the changes behind them - Read and update project settings, contributors, deployments, and automation rules +- Create, list, and revoke [project tokens](../learn/account-and-access/project-tokens.md) - Manage a team's members, invites, and email domains - Retrieve project metadata, account analytics, plan, and usage - Upload standalone images and videos and get shareable links for them @@ -35,9 +36,9 @@ The server is remote and uses the **streamable HTTP** transport — there is no Tools are generated directly from the [Argos REST API](https://argos-ci.com/docs/api-reference): every API operation that a user can call is exposed as an MCP tool with the same name, parameters, and permissions. When the API gains an endpoint, the MCP server gains the matching tool — with no client update on your side. -Agents can list builds and inspect their screenshot diffs, approve or reject changes, request reviewers, read and post comments, diagnose flaky tests and ignore their recurring changes, configure projects and their contributors, manage automation rules, administer a team's members and invites, upload and share [standalone media](../learn/media/) and read the comments left on it, and retrieve account analytics and usage. Ask your client to list the server's tools, or see the [API reference](https://argos-ci.com/docs/api-reference) for the underlying operations. +Agents can list builds and inspect their screenshot diffs, approve or reject changes, request reviewers, read and post comments, diagnose flaky tests and ignore their recurring changes, configure projects and their contributors, manage automation rules and project tokens, administer a team's members and invites, upload and share [standalone media](../learn/media/) and read the comments left on it, and retrieve account analytics and usage. Ask your client to list the server's tools, or see the [API reference](https://argos-ci.com/docs/api-reference) for the underlying operations. -What an agent may actually do is decided by the scopes you grant it, not by the tool list: `projects:read` for inspecting projects, builds and tests, `reviews:write` for reviews, review requests and ignoring changes, `comments:write` for comments and notification subscriptions, `projects:write` for project configuration and automation rules, `media:read` and `media:write` for uploading and managing shared media, and `account:admin` for team administration. +What an agent may actually do is decided by the scopes you grant it, not by the tool list: `projects:read` for inspecting projects, builds and tests, `reviews:write` for reviews, review requests and ignoring changes, `comments:write` for comments and notification subscriptions, `projects:write` for project configuration, automation rules and project tokens, `media:read` and `media:write` for uploading and managing shared media, and `account:admin` for team administration. ## Authentication diff --git a/docs/learn/account-and-access/README.md b/docs/learn/account-and-access/README.md index 9f0e4e44..c629f307 100644 --- a/docs/learn/account-and-access/README.md +++ b/docs/learn/account-and-access/README.md @@ -9,6 +9,7 @@ Manage your Argos account, how you sign in, and who on your team can access what * [Account management](account-management.md) – Sign up, create projects and teams, and manage login methods and emails * [Analytics](analytics.md) – Track builds, screenshots, change rate, and approval rate across your projects * [Team members & roles](team-members-and-roles.md) – Invite members and control their permissions with roles +* [Project tokens](project-tokens.md) – Create the tokens CI uploads with, scope their permissions, and rotate them without downtime * [Passkeys](passkeys.md) – Sign in with your fingerprint, face, screen lock, or a hardware security key * [GitHub single sign-on](github-single-sign-on.md) – Sync your Argos team with a GitHub organization * [SAML single sign-on](saml-single-sign-on.md) – Enforce single sign-on through your SAML identity provider diff --git a/docs/learn/account-and-access/account-management.md b/docs/learn/account-and-access/account-management.md index daf84e2a..51d828b2 100644 --- a/docs/learn/account-and-access/account-management.md +++ b/docs/learn/account-and-access/account-management.md @@ -44,7 +44,7 @@ Choose **Import a Git repository** and select a Git provider (GitHub or GitLab) {% tab title="Create without Git" %} Choose **Create a project without Git**, enter a **Project name**, and select **Create project**. -A project without a connected repository still receives builds through the [Argos CLI](../../sdks-reference/argos-command-line-interface-cli.md) using its project token. Features that depend on a repository — such as pull request comments — become available once you link one. +A project without a connected repository still receives builds through the [Argos CLI](../../sdks-reference/argos-command-line-interface-cli.md) using a [project token](project-tokens.md). Features that depend on a repository — such as pull request comments — become available once you link one. {% endtab %} {% endtabs %} @@ -68,7 +68,7 @@ Only project admins can delete a project. To keep it under another account inste 2. On the **Delete Project** card, select **Delete**. 3. Type the project's full name (`account/project`), then `delete my project`, and select **Delete**. -Argos warns that this can't be undone. Once the project is deleted, uploads with its project token fail and Argos stops updating its commit statuses. If the Argos check is a required status check in your Git provider, remove it there, or open pull requests keep waiting for it. +Argos warns that this can't be undone. Once the project is deleted, uploads with its project tokens fail and Argos stops updating its commit statuses. If the Argos check is a required status check in your Git provider, remove it there, or open pull requests keep waiting for it. ### Uninstall the GitHub App diff --git a/docs/learn/account-and-access/project-tokens.md b/docs/learn/account-and-access/project-tokens.md new file mode 100644 index 00000000..12d6d062 --- /dev/null +++ b/docs/learn/account-and-access/project-tokens.md @@ -0,0 +1,177 @@ +--- +description: "Create the project tokens CI uses to upload to Argos, choose their permissions and expiration, and rotate them without downtime." +--- + +# Project tokens + +A project token authenticates your CI with Argos. Store it as a CI secret and expose it as the `ARGOS_TOKEN` environment variable: the Argos SDK and CLI use it to upload builds and deployments, and to read project data. + +A project can have several tokens. Each one has: + +* a **name**, to recognize where it is used, such as "GitHub Actions"; +* the **projects** it is linked to: usually one, or several projects of the same account; +* its **permissions**, which decide what it can do on those projects; +* an **expiration** date, or none; +* a **last used** date, refreshed when CI authenticates with it. + +Argos shows a token once, when it is created, and only stores a hash of it. Nobody can display it again, administrators included. If you lose a token, create a new one and revoke the old one. + +{% hint style="info" %} +On GitHub Actions, you can skip the token: [OIDC or tokenless authentication](../integrations/github-actions-authentication.md) authenticates uploads without a secret to store or rotate. +{% endhint %} + +### Where tokens are managed + +Tokens belong to the account, team or personal, that owns the projects. + +* **Project settings → Authentication**, on the **Project tokens** card, lists the tokens linked to the project, including tokens linked to other projects too. [Project reviewers and administrators](team-members-and-roles.md) see the list. Project administrators create tokens for the project, and rename or revoke the tokens linked only to projects they administer. +* **Team Settings → Tokens** lists every project token of the team. Team owners create, rename and revoke any of them there, including tokens linked to several projects. On a personal account, the same list is in your account's **Settings → Tokens**. + +The list shows each token's name, permissions, other linked projects, and when it was created, last used, and expires. It never shows the token itself. + +### Create a token + +{% stepper %} +{% step %} + +### Open the token settings + +For a token used by one project, open the project's **Settings → Authentication** and, on the **Project tokens** card, select **Create token**. + +For a token linked to several projects, open **Team Settings → Tokens** and select **Create token**. +{% endstep %} + +{% step %} + +### Name the token + +Enter a **Token name** that says where the token is used, such as "GitHub Actions". In team settings, also tick the **Projects** to link it to. +{% endstep %} + +{% step %} + +### Choose its permissions and expiration + +The defaults, **Upload from CI** and **90 days**, are what CI needs to upload builds and deployments. See [Permissions](#permissions) and [Expiration](#expiration) to change them. +{% endstep %} + +{% step %} + +### Copy the token + +Select **Create token**. Argos shows the token once: copy it right away and store it as the `ARGOS_TOKEN` secret in your CI. +{% endstep %} +{% endstepper %} + +When you set up a new project, the **Getting started** page has a **Generate token** button. It creates a token named "Getting started", with the **Upload from CI** permissions, that expires in 90 days, and fills it into the commands on the page. Only project administrators see the button; other contributors are asked to get a token from an administrator. + +### Permissions + +When you create a token, choose a preset, or **Advanced** to tick individual permissions. + +| Preset | Permissions | Use it to | +| ---------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- | +| **Upload from CI** (default) | `builds:write`, `deployments:write` | Upload builds and deployments from CI. | +| **Read only** | `projects:read`, `media:read` | Read builds, screenshot diffs, tests, deployments and media, for example with the [Argos CLI](../../sdks-reference/argos-command-line-interface-cli.md). | +| **Full access** | All five permissions | Upload builds and deployments, read projects, and upload or delete media. | +| **Advanced** | The ones you tick | Combine permissions yourself. | + +| Permission | Shown as | Allows the token to | +| ------------------- | ------------------ | ---------------------------------------------------------------- | +| `builds:write` | Upload builds | Create, update and finalize builds and their screenshots. | +| `deployments:write` | Upload deployments | Create and finalize deployments. | +| `projects:read` | Read projects | Read builds, screenshot diffs, tests and deployments. | +| `media:read` | Read media | Read the images and videos uploaded to the projects. | +| `media:write` | Upload media | Upload images and videos, and delete the ones already uploaded. | + +Two uses need more than one preset covers: + +* [Uploading standalone media](../media/standalone-media-upload.md) needs **Upload media**, which **Upload from CI** doesn't include. +* [`argos baseline download`](../../sdks-reference/argos-command-line-interface-cli.md#downloading-screenshots-and-baselines) needs both **Read projects** and **Upload builds**. + +Pick the permissions under **Advanced**, or use **Full access**. + +A request that needs a permission the token lacks fails with a `403` error: "This project token lacks a permission. This endpoint requires: …", followed by the missing permission. + +### Expiration + +A new token expires in **90 days** by default. You can also pick 30, 60 or 180 days, 1 year, or **No expiration**. The dialog shows the date CI will stop uploading: [rotate the token](#rotate-a-token-without-downtime) before then. + +**No expiration** is discouraged. Such a token stays valid until someone revokes it, so if it leaks, in a CI log, a forked workflow or a former teammate's machine, whoever holds it can upload to your projects for as long as nobody notices. Argos asks you to confirm before creating one. + +Once a token has expired, its date shows as **Expired** in the list, and uploads with it fail with "This project token has expired, create a new one." + +### Rotate a token without downtime + +A project can have several tokens, so you can create a replacement before you revoke a token, and CI always has a valid one. + +{% stepper %} +{% step %} + +### Create the replacement + +[Create a token](#create-a-token) with the same projects and permissions as the old one. +{% endstep %} + +{% step %} + +### Update the CI secret + +Replace the value of the `ARGOS_TOKEN` secret with the new token, in every CI that uses the old one. +{% endstep %} + +{% step %} + +### Wait for the old token to go quiet + +Watch the **Last used** date of both tokens. Argos refreshes it within a few minutes of each use. Once the old token's date stops moving while the new one's keeps updating, nothing uses the old token anymore. +{% endstep %} + +{% step %} + +### Revoke the old token + +Open the old token's menu, select **Revoke**, and confirm. Anything still using it is rejected from its next upload. +{% endstep %} +{% endstepper %} + +Rotate a token before it expires, and when someone who had access to it leaves. If a token leaks, revoke it right away, without waiting for its last used date: uploads fail until CI has the replacement, but nobody else can use it. + +### Use a token linked to several projects + +A token linked to several projects doesn't tell Argos which project an upload is for. Set `ARGOS_PROJECT` to the project's full name, `owner/project`, next to `ARGOS_TOKEN`: + +{% code title=".github/workflows/argos.yml" %} +```yaml +env: + ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }} + ARGOS_PROJECT: my-team/my-project +``` +{% endcode %} + +Without it, the upload fails with "This project token is linked to several projects. Pass `project` as `owner/project` (`ARGOS_PROJECT` in the SDK) to choose one." A token linked to a single project doesn't need `ARGOS_PROJECT`. + +When you [transfer a project](../billing-and-subscription/how-to-subscribe.md#transfer-your-projects) to another account, the tokens linked only to that project move with it. A token linked to other projects too stays with the former account and stops working for the transferred project. + +### Legacy tokens + +Tokens created before Argos supported several tokens per project are listed as **Legacy token**. They keep every permission, never expire, and keep working: CI that uses one needs no change. Their **Last used** date reads **Never** until CI next uses them. + +To limit what a legacy token can do, [rotate it](#rotate-a-token-without-downtime) to a token with **Upload from CI** permissions and an expiration date. + +### Manage tokens with the API + +The [Argos REST API](https://argos-ci.com/docs/api-reference) lists, creates and revokes project tokens. These endpoints authenticate with a [personal access token](../../sdks-reference/argos-command-line-interface-cli.md#project-tokens-and-personal-access-tokens) or OAuth, not with a project token. + +| Endpoint | Does | Requires | +| --------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------- | +| `GET /projects/{owner}/{project}/tokens` | Lists the tokens linked to a project. | Reviewer role on the project. | +| `POST /projects/{owner}/{project}/tokens` | Creates a token linked to the project. | Administrator of the project. | +| `DELETE /projects/{owner}/{project}/tokens/{tokenId}` | Revokes a token linked to the project. | Administrator of every project the token is linked to, or of the account. | +| `GET /accounts/{accountSlug}/project-tokens` | Lists every project token of the account. | Administrator of the account. | +| `POST /accounts/{accountSlug}/project-tokens` | Creates a token linked to the listed `projects`. | Administrator of the account, or of every listed project. | +| `DELETE /accounts/{accountSlug}/project-tokens/{tokenId}` | Revokes a token of the account. | Administrator of the account, or of every project the token is linked to. | + +The token's value is only in the response to its creation, in the `token` field. Through the API, a token gets every permission unless you pass `permissions`, and never expires unless you pass `expireAt`: set both. + +The [Argos MCP server](../../agents/mcp-server.md) exposes the same operations as tools, so an AI agent can create, list and revoke project tokens with the permissions you grant it. diff --git a/docs/learn/account-and-access/security-and-compliance.md b/docs/learn/account-and-access/security-and-compliance.md index ffe02c72..6356ae84 100644 --- a/docs/learn/account-and-access/security-and-compliance.md +++ b/docs/learn/account-and-access/security-and-compliance.md @@ -32,7 +32,7 @@ Media sharing files have their own retention, which depends on your plan: see [S ### Export your data -There is no one-click export, but the [Argos CLI](../../sdks-reference/argos-command-line-interface-cli.md#downloading-screenshots-and-baselines) downloads screenshots with a project token. `argos build list` lists a project's builds, `argos build download` saves the screenshots of one build, and `argos baseline download` saves the screenshots of the project's latest baseline: +There is no one-click export, but the [Argos CLI](../../sdks-reference/argos-command-line-interface-cli.md#downloading-screenshots-and-baselines) downloads screenshots with a [project token](project-tokens.md) that can read the project (the **Read projects** permission; `baseline download` also needs **Upload builds**). `argos build list` lists a project's builds, `argos build download` saves the screenshots of one build, and `argos baseline download` saves the screenshots of the project's latest baseline: ```bash export ARGOS_TOKEN= diff --git a/docs/learn/billing-and-subscription/how-to-subscribe.md b/docs/learn/billing-and-subscription/how-to-subscribe.md index 18355a39..adfc95f1 100644 --- a/docs/learn/billing-and-subscription/how-to-subscribe.md +++ b/docs/learn/billing-and-subscription/how-to-subscribe.md @@ -52,6 +52,8 @@ Your existing projects stay on your personal account until you move them. For ea ![Selecting the destination team in the Transfer Project dialog](../../.gitbook/assets/transfer-project-select-team.png) The next screen lists the builds and screenshots that will move, and confirms the plan change, before you select **Transfer**. + +The [project tokens](../account-and-access/project-tokens.md) linked only to the project move with it, so CI keeps uploading. A token also linked to other projects stays with your personal account and stops working for the transferred project. {% endstep %} {% step %} diff --git a/docs/learn/deployments/README.md b/docs/learn/deployments/README.md index b5a5bba0..8717a011 100644 --- a/docs/learn/deployments/README.md +++ b/docs/learn/deployments/README.md @@ -150,7 +150,7 @@ The deploy command uses the same authentication as the rest of the Argos CLI. Se ARGOS_TOKEN= ``` -You can find the project token in **Settings → Authentication → Project token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](../integrations/github-actions-authentication.md) to avoid managing a secret. +`ARGOS_TOKEN` is a [project token](../account-and-access/project-tokens.md): create one in your project's **Settings → Authentication**, and copy it right away, as Argos only shows it once. On GitHub Actions, you can also use [OIDC or tokenless authentication](../integrations/github-actions-authentication.md) to avoid managing a secret. ### What's next diff --git a/docs/learn/deployments/use-deployments-in-ci.md b/docs/learn/deployments/use-deployments-in-ci.md index c661957b..3a3de1e5 100644 --- a/docs/learn/deployments/use-deployments-in-ci.md +++ b/docs/learn/deployments/use-deployments-in-ci.md @@ -45,7 +45,7 @@ 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](environments.md)). * `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 → Authentication → Project token**. +* `ARGOS_TOKEN` is a [project token](../account-and-access/project-tokens.md): create one in your project's **Settings → Authentication**, and copy it right away, as Argos only shows it once. ### Force a production deployment diff --git a/docs/learn/how-to-guides/ci-pipelines/run-argos-in-ci.md b/docs/learn/how-to-guides/ci-pipelines/run-argos-in-ci.md index 50f2ebd6..742def76 100644 --- a/docs/learn/how-to-guides/ci-pipelines/run-argos-in-ci.md +++ b/docs/learn/how-to-guides/ci-pipelines/run-argos-in-ci.md @@ -9,7 +9,7 @@ description: >- To run Argos in CI, run your tests as usual with the `ARGOS_TOKEN` environment variable set. The Argos SDK or CLI reads the commit, the branch, and the pull request from your CI provider, uploads the screenshots, and Argos compares them with the [baseline build](../../platform-fundamentals/baseline-build.md). On a CI provider that Argos doesn't detect, set `ARGOS_BRANCH` (and `ARGOS_COMMIT` if needed) yourself. -`ARGOS_TOKEN` is the project token from **Settings → Authentication → Project token**; store it as a secret in your CI. The examples below run Playwright tests: replace `npx playwright test` with your own test command, and follow the [quickstart](../../../quickstart/README.md) for your framework to set up the SDK. +`ARGOS_TOKEN` is a [project token](../../account-and-access/project-tokens.md); store it as a secret in your CI. The examples below run Playwright tests: replace `npx playwright test` with your own test command, and follow the [quickstart](../../../quickstart/README.md) for your framework to set up the SDK. {% hint style="info" %} Commit statuses and pull request comments come from the Argos [GitHub](../../integrations/github-integration.md) or [GitLab](../../integrations/gitlab-integration.md) integration, whichever CI runs your tests. Without one of them, review builds in the Argos dashboard. See [Other Git providers](../../integrations/other-git-providers.md). @@ -17,15 +17,11 @@ Commit statuses and pull request comments come from the Argos [GitHub](../../int ### Project token -Argos creates the project token when you create the project. You find it in the project's **Settings → Authentication**, on the **Project token** card. A project has one token at a time. +A project administrator creates the token in the project's **Settings → Authentication**: on the **Project tokens** card, select **Create token**. The default permissions, **Upload from CI**, cover builds and deployments. Argos shows the token only once, so copy it into your CI secret right away. A token linked to several projects is created in **Team Settings → Tokens**, and CI then also needs `ARGOS_PROJECT` set to `owner/project`. -If the token leaks, a project admin can replace it: +A project can have several tokens, so you can give each CI its own, and replace one without downtime: create the replacement, update the CI secret, then revoke the old token once its **Last used** date stops moving. See [Project tokens](../../account-and-access/project-tokens.md) for permissions, expiration, and rotation. -1. On the **Project token** card, select **Regenerate token**. -2. Type the project's full name (`account/project`) to confirm, then select **Regenerate**. -3. Update the `ARGOS_TOKEN` secret in your CI right away. - -The old token stops working immediately. Until you update the secret, uploads fail with "Project not found in Argos. If the issue persists, verify your token." +Uploads with a revoked or unknown token fail with "Project not found in Argos. If the issue persists, verify your token." Uploads with an expired token fail with "This project token has expired, create a new one." ### CI providers detected automatically @@ -137,6 +133,7 @@ On a CI provider that isn't in the table above, such as Jenkins, Azure Pipelines | Environment variable | Description | | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `ARGOS_TOKEN` | Project token. Required, except with GitHub Actions OIDC or tokenless authentication. | +| `ARGOS_PROJECT` | Project to upload to, as `owner/project`. Required with a [token linked to several projects](../../account-and-access/project-tokens.md#use-a-token-linked-to-several-projects). | | `ARGOS_BRANCH` | Branch of the build. | | `ARGOS_COMMIT` | Commit of the build, as a full 40-character SHA. | | `ARGOS_PR_NUMBER` | Number of the pull request associated with the build. | diff --git a/docs/learn/how-to-guides/migrate-to-argos/from-applitools.md b/docs/learn/how-to-guides/migrate-to-argos/from-applitools.md index 1ecf0f04..75ef2594 100644 --- a/docs/learn/how-to-guides/migrate-to-argos/from-applitools.md +++ b/docs/learn/how-to-guides/migrate-to-argos/from-applitools.md @@ -142,7 +142,7 @@ If you used the plain (non-fixture) API — `const eyes = new Eyes(runner); awai {% step %} ### Update the CI command -Rename the secret from `APPLITOOLS_API_KEY` to `ARGOS_TOKEN` and run your tests directly. +Replace the `APPLITOOLS_API_KEY` secret with an `ARGOS_TOKEN` secret holding a [project token](../../account-and-access/project-tokens.md), and run your tests directly. ```yaml - run: npx playwright test diff --git a/docs/learn/how-to-guides/migrate-to-argos/from-backstopjs.md b/docs/learn/how-to-guides/migrate-to-argos/from-backstopjs.md index d7f79f34..1870f025 100644 --- a/docs/learn/how-to-guides/migrate-to-argos/from-backstopjs.md +++ b/docs/learn/how-to-guides/migrate-to-argos/from-backstopjs.md @@ -163,7 +163,7 @@ There's no `backstop reference` step — run the tests on your default branch an ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }} ``` -`ARGOS_TOKEN` comes from **Settings → Authentication → Project token**. On GitHub Actions you can use [OIDC or tokenless authentication](../../integrations/github-actions-authentication.md) instead of a secret. +`ARGOS_TOKEN` is a [project token](../../account-and-access/project-tokens.md), created in your project's **Settings → Authentication** and shown only once. On GitHub Actions you can use [OIDC or tokenless authentication](../../integrations/github-actions-authentication.md) instead of a secret. {% endstep %} {% step %} diff --git a/docs/learn/how-to-guides/migrate-to-argos/from-chromatic.md b/docs/learn/how-to-guides/migrate-to-argos/from-chromatic.md index 01434b43..9366df71 100644 --- a/docs/learn/how-to-guides/migrate-to-argos/from-chromatic.md +++ b/docs/learn/how-to-guides/migrate-to-argos/from-chromatic.md @@ -124,7 +124,7 @@ Swap the single `chromatic` command for two steps: run the visual tests, then de {% endcolumn %} {% endcolumns %} -`ARGOS_TOKEN` comes from **Settings → Authentication → Project token**. On GitHub Actions you can use [OIDC or tokenless authentication](../../integrations/github-actions-authentication.md) instead of a secret. +`ARGOS_TOKEN` is a [project token](../../account-and-access/project-tokens.md), created in your project's **Settings → Authentication** and shown only once. On GitHub Actions you can use [OIDC or tokenless authentication](../../integrations/github-actions-authentication.md) instead of a secret. {% endstep %} {% step %} diff --git a/docs/learn/how-to-guides/migrate-to-argos/from-lost-pixel.md b/docs/learn/how-to-guides/migrate-to-argos/from-lost-pixel.md index 2835a37d..994e1447 100644 --- a/docs/learn/how-to-guides/migrate-to-argos/from-lost-pixel.md +++ b/docs/learn/how-to-guides/migrate-to-argos/from-lost-pixel.md @@ -131,7 +131,7 @@ Swap the Lost Pixel action for your test command, with `ARGOS_TOKEN` set: {% endcolumn %} {% endcolumns %} -For Storybook, use the workflow from the [Storybook quickstart](../../../quickstart/storybook-quickstart/). For custom shots, run `npm exec -- argos upload ` after your tests. `ARGOS_TOKEN` comes from **Settings → Authentication → Project token**; on GitHub Actions you can use [OIDC or tokenless authentication](../../integrations/github-actions-authentication.md) instead of a secret. +For Storybook, use the workflow from the [Storybook quickstart](../../../quickstart/storybook-quickstart/). For custom shots, run `npm exec -- argos upload ` after your tests. `ARGOS_TOKEN` is a [project token](../../account-and-access/project-tokens.md), created in your project's **Settings → Authentication** and shown only once; on GitHub Actions you can use [OIDC or tokenless authentication](../../integrations/github-actions-authentication.md) instead of a secret. {% endstep %} {% step %} diff --git a/docs/learn/how-to-guides/migrate-to-argos/from-percy.md b/docs/learn/how-to-guides/migrate-to-argos/from-percy.md index ac5a8b3e..6e912e7d 100644 --- a/docs/learn/how-to-guides/migrate-to-argos/from-percy.md +++ b/docs/learn/how-to-guides/migrate-to-argos/from-percy.md @@ -37,7 +37,7 @@ Beyond the capture model, the reasons teams pick Argos over Percy: | `PERCY_TOKEN` | `ARGOS_TOKEN` | | `.percy.yml` → `snapshot.widths` | [Responsive viewports](../visual-coverage/responsive-viewports.md) | | `.percy.yml` → `percy-css` / `percyCSS` | [Injecting CSS](../visual-coverage/injecting-css.md) | -| Percy project + browsers dashboard | Argos project ([Settings → Authentication → Project token](https://app.argos-ci.com/)) | +| Percy project + browsers dashboard | Argos project and its [project token](../../account-and-access/project-tokens.md) | | Percy build review | [Review a build](../../review-workflow/review-a-build.md) + PR comment | ## Migrate a Playwright project @@ -175,7 +175,7 @@ Drop `percy exec --` and run your tests directly. Rename the token secret from ` {% endcolumn %} {% endcolumns %} -`ARGOS_TOKEN` comes from **Settings → Authentication → Project token** in your Argos project. On GitHub Actions you can skip the secret entirely with [OIDC or tokenless authentication](../../integrations/github-actions-authentication.md). +`ARGOS_TOKEN` is a [project token](../../account-and-access/project-tokens.md), created in your Argos project's **Settings → Authentication** and shown only once. On GitHub Actions you can skip the secret entirely with [OIDC or tokenless authentication](../../integrations/github-actions-authentication.md). {% endstep %} {% step %} diff --git a/docs/learn/how-to-guides/migrate-to-argos/from-playwright-native-screenshots.md b/docs/learn/how-to-guides/migrate-to-argos/from-playwright-native-screenshots.md index fb69e7da..98e665ab 100644 --- a/docs/learn/how-to-guides/migrate-to-argos/from-playwright-native-screenshots.md +++ b/docs/learn/how-to-guides/migrate-to-argos/from-playwright-native-screenshots.md @@ -154,7 +154,7 @@ Run your tests in CI with `ARGOS_TOKEN` set. **Run on your default branch first* ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }} ``` -`ARGOS_TOKEN` comes from **Settings → Authentication → Project token**. On GitHub Actions you can use [OIDC or tokenless authentication](../../integrations/github-actions-authentication.md) instead. +`ARGOS_TOKEN` is a [project token](../../account-and-access/project-tokens.md), created in your project's **Settings → Authentication** and shown only once. On GitHub Actions you can use [OIDC or tokenless authentication](../../integrations/github-actions-authentication.md) instead. {% endstep %} {% endstepper %} diff --git a/docs/learn/how-to-guides/migrate-to-argos/from-vitest-native-screenshots.md b/docs/learn/how-to-guides/migrate-to-argos/from-vitest-native-screenshots.md index 8be0fad7..eadf384c 100644 --- a/docs/learn/how-to-guides/migrate-to-argos/from-vitest-native-screenshots.md +++ b/docs/learn/how-to-guides/migrate-to-argos/from-vitest-native-screenshots.md @@ -174,7 +174,7 @@ Run your tests in CI with `ARGOS_TOKEN` set. **Run on your default branch first* ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }} ``` -`ARGOS_TOKEN` comes from **Settings → Authentication → Project token**. On GitHub Actions you can use [OIDC or tokenless authentication](../../integrations/github-actions-authentication.md) instead of a secret. +`ARGOS_TOKEN` is a [project token](../../account-and-access/project-tokens.md), created in your project's **Settings → Authentication** and shown only once. On GitHub Actions you can use [OIDC or tokenless authentication](../../integrations/github-actions-authentication.md) instead of a secret. {% endstep %} {% endstepper %} diff --git a/docs/learn/integrations/github-actions-authentication.md b/docs/learn/integrations/github-actions-authentication.md index dfe923c6..1c398421 100644 --- a/docs/learn/integrations/github-actions-authentication.md +++ b/docs/learn/integrations/github-actions-authentication.md @@ -18,7 +18,7 @@ The SDK selects an authentication method in this order: The SDK doesn't read your project settings. As soon as the job has `id-token: write`, it uses OIDC, even if OIDC is disabled on the project. In that case the upload fails; the SDK does not fall back to tokenless. -* **Project token (`ARGOS_TOKEN`)**: A long-lived secret stored in your repository. Works on every CI provider, but needs to be provisioned and rotated. This is the only option outside GitHub Actions. +* **Project token (`ARGOS_TOKEN`)**: A secret stored in your repository. Works on every CI provider, but needs to be [created and rotated](../account-and-access/project-tokens.md) before it expires. This is the only option outside GitHub Actions. * **OIDC**: A short-lived identity token signed by GitHub, verified by Argos on every upload. The most secure option — prefer it when your workflow can use it. * **Tokenless**: Argos verifies the upload by looking up the workflow run on GitHub. Nothing to add to the workflow once it is enabled on the project, and the only method that works on pull requests from forks. diff --git a/docs/learn/integrations/github-integration.md b/docs/learn/integrations/github-integration.md index 88534ab8..074e99f3 100644 --- a/docs/learn/integrations/github-integration.md +++ b/docs/learn/integrations/github-integration.md @@ -214,7 +214,7 @@ Self-hosted GitHub Enterprise Server deployments are supported on the Argos Ente Uploads from GitHub Actions can authenticate in three ways: -* **`ARGOS_TOKEN`** — a project token stored as a GitHub secret (used in the examples above). +* **`ARGOS_TOKEN`** — a [project token](../account-and-access/project-tokens.md) stored as a GitHub secret (used in the examples above). * [**GitHub OIDC**](github-actions-authentication.md#oidc) — short-lived signed tokens with no secret to manage. Preferred where available. * [**Tokenless authentication**](github-actions-authentication.md#tokenless-authentication) — the automatic fallback for pull requests from forked repositories. diff --git a/docs/learn/media/standalone-media-upload.md b/docs/learn/media/standalone-media-upload.md index abd8229d..8106c64f 100644 --- a/docs/learn/media/standalone-media-upload.md +++ b/docs/learn/media/standalone-media-upload.md @@ -165,12 +165,14 @@ Resolve only what you actually fixed. A resolved thread drops out of the next `m | Command | Token | | -------------------------------- | ---------------------------------------------------------------------------------------------- | -| `media upload`, `media update` | Project token (`ARGOS_TOKEN`, or tokenless CI for upload), or a personal access token with review access. | -| `media get`, `list`, `versions` | Either token type, with access to the project. | -| `media delete` | Project token, or a personal access token with **administrator** rights on the project — a share URL may already be pasted somewhere, and deleting the media breaks it. | +| `media upload`, `media update` | Project token (`ARGOS_TOKEN`) with **Upload media**, tokenless CI for upload, or a personal access token with review access. | +| `media get`, `list`, `versions` | Project token with **Read media**, or a personal access token with access to the project. | +| `media delete` | Project token with **Upload media**, or a personal access token with **administrator** rights on the project — a share URL may already be pasted somewhere, and deleting the media breaks it. | | `media comment …` | Personal access token, reading included. | -With a personal access token, `media upload` and `media list` need the project named: `--project ` or `ARGOS_PROJECT`. A project token already identifies its project. +A project token's [permissions](../account-and-access/project-tokens.md#permissions) must cover the command: **Upload from CI**, the default for new tokens, doesn't include the media permissions, while **Full access** and legacy tokens do. + +With a personal access token, `media upload` and `media list` need the project named: `--project ` or `ARGOS_PROJECT`. So does a project token linked to several projects; a project token linked to a single project already identifies it. ### From the Node.js SDK @@ -205,7 +207,7 @@ curl -X POST https://api.argos-ci.com/v2/media \ }' ``` -`state`, `description`, `visibility`, `branch` and `prNumber` are optional. With a personal access token, add `"project": "acme/web"`; a project token already identifies its project. +`state`, `description`, `visibility`, `branch` and `prNumber` are optional. With a personal access token, add `"project": "acme/web"`, as you do with a project token linked to several projects; a project token linked to a single project already identifies it. `POST` the file to `upload.url` as `multipart/form-data`, appending every entry of `upload.fields` **before** the `file` part — the target stays valid for 30 minutes — then call `POST /media/{mediaId}/finalize`. Finalizing checks the file is what it claims to be, records an image's dimensions, bills the upload, and makes it reachable. When `upload` comes back `null`, Argos already holds this exact file and both steps are unnecessary. diff --git a/docs/learn/reliability-and-flakiness/fix-flaky-tests-with-ai-agents.md b/docs/learn/reliability-and-flakiness/fix-flaky-tests-with-ai-agents.md index 4ac64b71..486148e2 100644 --- a/docs/learn/reliability-and-flakiness/fix-flaky-tests-with-ai-agents.md +++ b/docs/learn/reliability-and-flakiness/fix-flaky-tests-with-ai-agents.md @@ -16,7 +16,7 @@ The [test page](test-page.md) hands you a prompt that does exactly that. - A flaky test on the [Tests dashboard](tests-dashboard.md). - An AI agent with access to the repository that contains the test. - The [Argos CLI](../../sdks-reference/argos-command-line-interface-cli.md), the [MCP server](../../agents/mcp-server.md), or plain HTTP access to the [REST API](https://argos-ci.com/docs/api-reference) — whichever your agent already has. -- A token the agent can read with. A **project token** is enough to read a test and its changes; ignoring a change needs a [personal access token](../../sdks-reference/argos-command-line-interface-cli.md#project-tokens-and-personal-access-tokens). +- A token the agent can read with. A [project token](../account-and-access/project-tokens.md) with the **Read only** permissions is enough to read a test and its changes; ignoring a change needs a [personal access token](../../sdks-reference/argos-command-line-interface-cli.md#project-tokens-and-personal-access-tokens). ### Quick start diff --git a/docs/learn/review-workflow/review-builds-with-ai-agents.md b/docs/learn/review-workflow/review-builds-with-ai-agents.md index 22b699ed..0b0151ab 100644 --- a/docs/learn/review-workflow/review-builds-with-ai-agents.md +++ b/docs/learn/review-workflow/review-builds-with-ai-agents.md @@ -13,7 +13,7 @@ By default, ask the agent to summarize the visual changes first. If you want it * A pull request with an Argos build. * The [Argos CLI](../../sdks-reference/argos-command-line-interface-cli.md). * The [Argos agent skills](../../agents/agent-skills.md), when your assistant supports skills. -* An Argos project token to read build data with `build get` and `build snapshots`. +* An Argos [project token](../account-and-access/project-tokens.md) with the **Read only** permissions, to read build data with `build get` and `build snapshots`. * A user token to create a build review, only if you want the agent to approve or request changes. ### Quick start @@ -109,7 +109,7 @@ After summarizing the visual changes, create an Argos build review with the appr #### Authentication details -Reading build data requires a project token. Creating a build review requires a user token because the review is attributed to an Argos user and checked against that user's project permissions. +Reading build data requires a project token with the **Read projects** permission, which the **Read only** and **Full access** presets include; the default **Upload from CI** preset doesn't. Creating a build review requires a user token because the review is attributed to an Argos user and checked against that user's project permissions. For details about token precedence, `--token`, and personal access tokens, see [Argos CLI authentication](../../sdks-reference/argos-command-line-interface-cli.md#authentication). diff --git a/docs/quickstart/any-test-framework.md b/docs/quickstart/any-test-framework.md index a57f5d4c..b62aee89 100644 --- a/docs/quickstart/any-test-framework.md +++ b/docs/quickstart/any-test-framework.md @@ -88,7 +88,7 @@ jobs: ``` {% endcode %} -`ARGOS_TOKEN` is the project token from **Settings → Authentication → Project token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](../learn/integrations/github-actions-authentication.md) to avoid managing a secret. On other CI providers, set `ARGOS_TOKEN` as a secret environment variable. For GitLab CI, CircleCI, Buildkite, and other providers, see [Run Argos in CI](../learn/how-to-guides/ci-pipelines/run-argos-in-ci.md). +`ARGOS_TOKEN` is a [project token](../learn/account-and-access/project-tokens.md): create one in your project's **Settings → Authentication**, and copy it right away, as Argos only shows it once. On GitHub Actions, you can also use [OIDC or tokenless authentication](../learn/integrations/github-actions-authentication.md) to avoid managing a secret. On other CI providers, set `ARGOS_TOKEN` as a secret environment variable. For GitLab CI, CircleCI, Buildkite, and other providers, see [Run Argos in CI](../learn/how-to-guides/ci-pipelines/run-argos-in-ci.md). The CLI detects your CI context (commit, branch, pull request) automatically. See the [CLI reference](../sdks-reference/argos-command-line-interface-cli.md) for all options. {% endstep %} diff --git a/docs/quickstart/cypress-quickstart.md b/docs/quickstart/cypress-quickstart.md index de0c7081..868a9f7e 100644 --- a/docs/quickstart/cypress-quickstart.md +++ b/docs/quickstart/cypress-quickstart.md @@ -157,7 +157,7 @@ jobs: ``` {% endcode %} -`ARGOS_TOKEN` is the project token from **Settings → Authentication → Project token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](../learn/integrations/github-actions-authentication.md) to avoid managing a secret. On other CI providers, pass the token with the `ARGOS_TOKEN` environment variable or the task's `token` option. For GitLab CI, CircleCI, Buildkite, and other providers, see [Run Argos in CI](../learn/how-to-guides/ci-pipelines/run-argos-in-ci.md). +`ARGOS_TOKEN` is a [project token](../learn/account-and-access/project-tokens.md): create one in your project's **Settings → Authentication**, and copy it right away, as Argos only shows it once. On GitHub Actions, you can also use [OIDC or tokenless authentication](../learn/integrations/github-actions-authentication.md) to avoid managing a secret. On other CI providers, pass the token with the `ARGOS_TOKEN` environment variable or the task's `token` option. For GitLab CI, CircleCI, Buildkite, and other providers, see [Run Argos in CI](../learn/how-to-guides/ci-pipelines/run-argos-in-ci.md). {% endstep %} {% endstepper %} diff --git a/docs/quickstart/playwright-quickstart.md b/docs/quickstart/playwright-quickstart.md index b4330954..f5001597 100644 --- a/docs/quickstart/playwright-quickstart.md +++ b/docs/quickstart/playwright-quickstart.md @@ -172,7 +172,7 @@ jobs: ``` {% endcode %} -`ARGOS_TOKEN` is the project token from **Settings → Authentication → Project token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](../learn/integrations/github-actions-authentication.md) to avoid managing a secret. On other CI providers, pass the token with the `ARGOS_TOKEN` environment variable or the reporter's `token` option. For GitLab CI, CircleCI, Buildkite, and other providers, see [Run Argos in CI](../learn/how-to-guides/ci-pipelines/run-argos-in-ci.md). +`ARGOS_TOKEN` is a [project token](../learn/account-and-access/project-tokens.md): create one in your project's **Settings → Authentication**, and copy it right away, as Argos only shows it once. On GitHub Actions, you can also use [OIDC or tokenless authentication](../learn/integrations/github-actions-authentication.md) to avoid managing a secret. On other CI providers, pass the token with the `ARGOS_TOKEN` environment variable or the reporter's `token` option. For GitLab CI, CircleCI, Buildkite, and other providers, see [Run Argos in CI](../learn/how-to-guides/ci-pipelines/run-argos-in-ci.md). {% endstep %} {% endstepper %} diff --git a/docs/quickstart/puppeteer-quickstart.md b/docs/quickstart/puppeteer-quickstart.md index 9fea7230..0fcd9294 100644 --- a/docs/quickstart/puppeteer-quickstart.md +++ b/docs/quickstart/puppeteer-quickstart.md @@ -127,7 +127,7 @@ jobs: {% endcode %} -`ARGOS_TOKEN` is the project token from **Settings → Authentication → Project token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](../learn/integrations/github-actions-authentication.md) to avoid managing a secret. For GitLab CI, CircleCI, Buildkite, and other providers, see [Run Argos in CI](../learn/how-to-guides/ci-pipelines/run-argos-in-ci.md). +`ARGOS_TOKEN` is a [project token](../learn/account-and-access/project-tokens.md): create one in your project's **Settings → Authentication**, and copy it right away, as Argos only shows it once. On GitHub Actions, you can also use [OIDC or tokenless authentication](../learn/integrations/github-actions-authentication.md) to avoid managing a secret. For GitLab CI, CircleCI, Buildkite, and other providers, see [Run Argos in CI](../learn/how-to-guides/ci-pipelines/run-argos-in-ci.md). {% endstep %} {% endstepper %} diff --git a/docs/quickstart/storybook-quickstart/README.md b/docs/quickstart/storybook-quickstart/README.md index 72e4f236..bcd4c5f5 100644 --- a/docs/quickstart/storybook-quickstart/README.md +++ b/docs/quickstart/storybook-quickstart/README.md @@ -225,7 +225,7 @@ jobs: ``` {% endcode %} -`ARGOS_TOKEN` is the project token from **Settings → Authentication → Project token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](../../learn/integrations/github-actions-authentication.md) to avoid managing a secret. +`ARGOS_TOKEN` is a [project token](../../learn/account-and-access/project-tokens.md): create one in your project's **Settings → Authentication**, and copy it right away, as Argos only shows it once. On GitHub Actions, you can also use [OIDC or tokenless authentication](../../learn/integrations/github-actions-authentication.md) to avoid managing a secret. For other CI providers, see [Run Argos in CI](../../learn/how-to-guides/ci-pipelines/run-argos-in-ci.md) for the tests and [Use deployments in CI](../../learn/deployments/use-deployments-in-ci.md) for the deployment. {% endstep %} diff --git a/docs/quickstart/storybook-quickstart/storybook-legacy-less-than-v8-quickstart.md b/docs/quickstart/storybook-quickstart/storybook-legacy-less-than-v8-quickstart.md index 8983f448..a8cf805d 100644 --- a/docs/quickstart/storybook-quickstart/storybook-legacy-less-than-v8-quickstart.md +++ b/docs/quickstart/storybook-quickstart/storybook-legacy-less-than-v8-quickstart.md @@ -118,7 +118,7 @@ jobs: ``` {% endcode %} -`ARGOS_TOKEN` is the project token from **Settings → Authentication → Project token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](../../learn/integrations/github-actions-authentication.md) to avoid managing a secret. +`ARGOS_TOKEN` is a [project token](../../learn/account-and-access/project-tokens.md): create one in your project's **Settings → Authentication**, and copy it right away, as Argos only shows it once. On GitHub Actions, you can also use [OIDC or tokenless authentication](../../learn/integrations/github-actions-authentication.md) to avoid managing a secret. {% endstep %} {% endstepper %} diff --git a/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart.md b/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart.md index 6bf97c4f..2a74f5eb 100644 --- a/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart.md +++ b/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart.md @@ -147,7 +147,7 @@ jobs: ``` {% endcode %} -`ARGOS_TOKEN` is the project token from **Settings → Authentication → Project token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](../../learn/integrations/github-actions-authentication.md) to avoid managing a secret. +`ARGOS_TOKEN` is a [project token](../../learn/account-and-access/project-tokens.md): create one in your project's **Settings → Authentication**, and copy it right away, as Argos only shows it once. On GitHub Actions, you can also use [OIDC or tokenless authentication](../../learn/integrations/github-actions-authentication.md) to avoid managing a secret. To learn how to run tests on a deployed Storybook, refer to the [Storybook Test Runner documentation](https://storybook.js.org/docs/writing-tests/integrations/test-runner). {% endstep %} diff --git a/docs/quickstart/vitest-quickstart.md b/docs/quickstart/vitest-quickstart.md index aff1f382..c822dc50 100644 --- a/docs/quickstart/vitest-quickstart.md +++ b/docs/quickstart/vitest-quickstart.md @@ -217,7 +217,7 @@ jobs: ``` {% endcode %} -`ARGOS_TOKEN` is the project token from **Settings → Authentication → Project token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](../learn/integrations/github-actions-authentication.md) to avoid managing a secret. On other CI providers, pass the token with the `ARGOS_TOKEN` environment variable or the plugin's `token` option. For GitLab CI, CircleCI, Buildkite, and other providers, see [Run Argos in CI](../learn/how-to-guides/ci-pipelines/run-argos-in-ci.md). +`ARGOS_TOKEN` is a [project token](../learn/account-and-access/project-tokens.md): create one in your project's **Settings → Authentication**, and copy it right away, as Argos only shows it once. On GitHub Actions, you can also use [OIDC or tokenless authentication](../learn/integrations/github-actions-authentication.md) to avoid managing a secret. On other CI providers, pass the token with the `ARGOS_TOKEN` environment variable or the plugin's `token` option. For GitLab CI, CircleCI, Buildkite, and other providers, see [Run Argos in CI](../learn/how-to-guides/ci-pipelines/run-argos-in-ci.md). {% endstep %} {% endstepper %} diff --git a/docs/quickstart/webdriverio-quickstart.md b/docs/quickstart/webdriverio-quickstart.md index 36937673..81a4c7f8 100644 --- a/docs/quickstart/webdriverio-quickstart.md +++ b/docs/quickstart/webdriverio-quickstart.md @@ -110,7 +110,7 @@ jobs: ``` {% endcode %} -`ARGOS_TOKEN` is the project token from **Settings → Authentication → Project token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](../learn/integrations/github-actions-authentication.md) to avoid managing a secret. For GitLab CI, CircleCI, Buildkite, and other providers, see [Run Argos in CI](../learn/how-to-guides/ci-pipelines/run-argos-in-ci.md). +`ARGOS_TOKEN` is a [project token](../learn/account-and-access/project-tokens.md): create one in your project's **Settings → Authentication**, and copy it right away, as Argos only shows it once. On GitHub Actions, you can also use [OIDC or tokenless authentication](../learn/integrations/github-actions-authentication.md) to avoid managing a secret. For GitLab CI, CircleCI, Buildkite, and other providers, see [Run Argos in CI](../learn/how-to-guides/ci-pipelines/run-argos-in-ci.md). {% endstep %} {% endstepper %} diff --git a/docs/sdks-reference/argos-command-line-interface-cli.md b/docs/sdks-reference/argos-command-line-interface-cli.md index c99e5466..f997ee6c 100644 --- a/docs/sdks-reference/argos-command-line-interface-cli.md +++ b/docs/sdks-reference/argos-command-line-interface-cli.md @@ -45,7 +45,7 @@ bun add --dev @argos-ci/cli Authentication depends on where the CLI runs: -* **In CI**, set the `ARGOS_TOKEN` environment variable to your project token (from **Settings → Authentication → Project token**), usually as a CI secret. On GitHub Actions, you can also use [OIDC or tokenless authentication](../learn/integrations/github-actions-authentication.md) to avoid managing a secret. +* **In CI**, set the `ARGOS_TOKEN` environment variable to a [project token](../learn/account-and-access/project-tokens.md), usually as a CI secret. Create it in your project's **Settings → Authentication**, and copy it right away: Argos only shows it once. A token linked to several projects also needs `ARGOS_PROJECT` set to `owner/project`. On GitHub Actions, you can also use [OIDC or tokenless authentication](../learn/integrations/github-actions-authentication.md) to avoid managing a secret. * **Locally**, sign in once with the browser-based login flow: ```bash @@ -66,11 +66,11 @@ Do not use `argos login` in CI. CI uploads should use `ARGOS_TOKEN` or [GitHub O #### Project tokens and personal access tokens -Uploads and read-only commands — `build list`, `build get`, `build snapshots`, `build download`, `test list`, `test get`, `test changes`, `change list`, `project get`, `project deployments`, `project domain get`, `media list`, `media get`, `media versions` — work with a **project token**. Anything attributed to a user requires a **personal access token**, because the action is checked against that user's permissions: submitting or dismissing a review, requesting reviewers, posting comments (on builds, tests, and media alike), ignoring a change, configuring a project, and administering a team. +Uploads and read-only commands — `build list`, `build get`, `build snapshots`, `build download`, `test list`, `test get`, `test changes`, `change list`, `project get`, `project deployments`, `project domain get`, `media list`, `media get`, `media versions` — work with a **project token** that has the matching [permissions](../learn/account-and-access/project-tokens.md#permissions): **Upload from CI** for uploads, **Read only** for read-only commands. Anything attributed to a user requires a **personal access token**, because the action is checked against that user's permissions: submitting or dismissing a review, requesting reviewers, posting comments (on builds, tests, and media alike), ignoring a change, configuring a project, and administering a team. Two read-only commands are the exception: `project contributor list` and `review reviewer list` return users, so they need a personal access token to resolve them against — a project token carries no identity. -`baseline download` is the opposite exception: it only accepts a project token, and reads that token's own project. +`baseline download` is the opposite exception: it only accepts a project token, and reads that token's own project. It looks the baseline up the way an upload does, so the token needs both **Read projects** and **Upload builds**: use **Full access**, or pick both under **Advanced**. To create a personal access token manually, go to your personal account settings, open **Tokens**, then select **Generate new token**. @@ -226,7 +226,7 @@ These commands read data, so a project token is enough. argos build list --branch main --limit 10 ``` -`--branch` and `--commit` keep the builds of one branch or one commit. `--commit` takes a full 40-character SHA; to match a shorter one, use `--search`, which matches the build name, part of the branch, or the start of the commit. A project token reads its own project; with a [personal access token](#project-tokens-and-personal-access-tokens), pass `--project owner/project` or set `ARGOS_PROJECT`. +`--branch` and `--commit` keep the builds of one branch or one commit. `--commit` takes a full 40-character SHA; to match a shorter one, use `--search`, which matches the build name, part of the branch, or the start of the commit. A project token linked to a single project reads that project; with a [personal access token](#project-tokens-and-personal-access-tokens), pass `--project owner/project` or set `ARGOS_PROJECT`. A `` is a build number or a full Argos build URL; with a number, add `--project team/project`, since a URL already carries it. @@ -259,7 +259,7 @@ argos test changes --json `test changes` lists its distinct changes, the ones that came back most often first. Each carries its `id`, whether it is `ignored`, its `occurrences`, when it was `firstSeen` and `lastSeen`, and the `diff` of its latest occurrence with the mask, baseline, and captured screenshot URLs. `--ignored true|false` narrows the list to ignored or still-reviewable changes. -A `` carries the project name but not the account, so pass `--project owner/project` (or `ARGOS_PROJECT`) — unless you authenticate with a project token, which already identifies its own project. +A `` carries the project name but not the account, so pass `--project owner/project` (or `ARGOS_PROJECT`) — unless you authenticate with a project token linked to a single project, which already identifies it. ### Silencing a flaky change From 5cbfb39ade58b14de60d8ac01628dd0177848eff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Greg=20Berg=C3=A9?= Date: Thu, 5 Nov 2026 12:06:21 +0100 Subject: [PATCH 2/3] docs(cli): project token commands and --project on baseline download argos-ci/argos-javascript#411 adds `argos project token` and `argos account project-token` (list, create, revoke), and lets `finalize`, `skip`, `deploy` and `baseline download` take `--project` for a token linked to several projects. - CLI reference: add both command groups, with their defaults (every permission, no expiration) and the roles they need; drop "baseline download has no --project flag"; say what --project does for a multi-project token. - Project tokens: mention the CLI next to the API, and that ARGOS_PROJECT naming another project fails with a 401 for a single-project token. Co-Authored-By: Claude Opus 5.5 --- .../account-and-access/project-tokens.md | 8 +++--- .../argos-command-line-interface-cli.md | 26 ++++++++++++++++--- 2 files changed, 27 insertions(+), 7 deletions(-) diff --git a/docs/learn/account-and-access/project-tokens.md b/docs/learn/account-and-access/project-tokens.md index 12d6d062..a4d9a7c6 100644 --- a/docs/learn/account-and-access/project-tokens.md +++ b/docs/learn/account-and-access/project-tokens.md @@ -149,7 +149,7 @@ env: ``` {% endcode %} -Without it, the upload fails with "This project token is linked to several projects. Pass `project` as `owner/project` (`ARGOS_PROJECT` in the SDK) to choose one." A token linked to a single project doesn't need `ARGOS_PROJECT`. +Without it, the upload fails with "This project token is linked to several projects. Pass `project` as `owner/project` (`ARGOS_PROJECT` in the SDK) to choose one." A token linked to a single project doesn't need `ARGOS_PROJECT`; if you set it anyway, it must name that project, or the upload fails with a `401` error. When you [transfer a project](../billing-and-subscription/how-to-subscribe.md#transfer-your-projects) to another account, the tokens linked only to that project move with it. A token linked to other projects too stays with the former account and stops working for the transferred project. @@ -159,9 +159,9 @@ Tokens created before Argos supported several tokens per project are listed as * To limit what a legacy token can do, [rotate it](#rotate-a-token-without-downtime) to a token with **Upload from CI** permissions and an expiration date. -### Manage tokens with the API +### Manage tokens from the CLI or the API -The [Argos REST API](https://argos-ci.com/docs/api-reference) lists, creates and revokes project tokens. These endpoints authenticate with a [personal access token](../../sdks-reference/argos-command-line-interface-cli.md#project-tokens-and-personal-access-tokens) or OAuth, not with a project token. +The [Argos CLI](../../sdks-reference/argos-command-line-interface-cli.md#configuring-a-project) lists, creates and revokes tokens with `argos project token` and, for every token of an account, `argos account project-token`. Both call the [Argos REST API](https://argos-ci.com/docs/api-reference) endpoints below, which authenticate with a [personal access token](../../sdks-reference/argos-command-line-interface-cli.md#project-tokens-and-personal-access-tokens) or OAuth, not with a project token. | Endpoint | Does | Requires | | --------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------- | @@ -172,6 +172,6 @@ The [Argos REST API](https://argos-ci.com/docs/api-reference) lists, creates and | `POST /accounts/{accountSlug}/project-tokens` | Creates a token linked to the listed `projects`. | Administrator of the account, or of every listed project. | | `DELETE /accounts/{accountSlug}/project-tokens/{tokenId}` | Revokes a token of the account. | Administrator of the account, or of every project the token is linked to. | -The token's value is only in the response to its creation, in the `token` field. Through the API, a token gets every permission unless you pass `permissions`, and never expires unless you pass `expireAt`: set both. +The token's value is only in the response to its creation, in the `token` field. Through the API and the CLI, a token gets every permission unless you pass `permissions`, and never expires unless you pass `expireAt` (`--expires-in` or `--expire-at` in the CLI): set both. The [Argos MCP server](../../agents/mcp-server.md) exposes the same operations as tools, so an AI agent can create, list and revoke project tokens with the permissions you grant it. diff --git a/docs/sdks-reference/argos-command-line-interface-cli.md b/docs/sdks-reference/argos-command-line-interface-cli.md index f997ee6c..3390aa4d 100644 --- a/docs/sdks-reference/argos-command-line-interface-cli.md +++ b/docs/sdks-reference/argos-command-line-interface-cli.md @@ -70,7 +70,7 @@ Uploads and read-only commands — `build list`, `build get`, `build snapshots`, Two read-only commands are the exception: `project contributor list` and `review reviewer list` return users, so they need a personal access token to resolve them against — a project token carries no identity. -`baseline download` is the opposite exception: it only accepts a project token, and reads that token's own project. It looks the baseline up the way an upload does, so the token needs both **Read projects** and **Upload builds**: use **Full access**, or pick both under **Advanced**. +`baseline download` is the opposite exception: it only accepts a project token, and reads that token's project. It looks the baseline up the way an upload does, so the token needs both **Read projects** and **Upload builds**: use **Full access**, or pick both under **Advanced**. To create a personal access token manually, go to your personal account settings, open **Tokens**, then select **Generate new token**. @@ -109,11 +109,13 @@ Run `argos --help` for a command's exact arguments, flags, and default | `project contributor list \| set \| remove` | Manage who can reach a project outside the team's own roles. | | `project deployments` | List a project's deployments, most recent first. | | `project domain get \| set` | Read or set the domain production deployments are served on. | +| `project token list \| create \| revoke` | Manage the tokens CI authenticates with on a project. | | `automation ` | List, create, replace, and deactivate a project's automation rules. | | `account get \| update` | Read plan and usage, and set the role users get when they join. | | `account member ` | List a team's members, change their role, remove them. | | `account invite ` | Invite people, cancel invites, rotate the invite link. | | `account domain ` | Manage the email domains a team is open to. | +| `account project-token ` | Manage every project token of an account, multi-project ones too. | | `media upload ` | Upload standalone images or videos and print their share URLs. | | `media list` | List a project's uploaded media, most recent first. | | `media get \| update \| delete ` | Fetch, edit, or delete one uploaded media. | @@ -176,7 +178,7 @@ Use `-f` or `--files` to upload text-based artifacts such as JSON, YAML, XML, HT #### Specify the project -Use `--project ` to set the Argos project slug (`account/project-name`). This disambiguates [tokenless authentication](../learn/integrations/github-actions-authentication.md#tokenless-authentication) when multiple Argos projects are linked to the same repository: +Use `--project `, or `ARGOS_PROJECT`, to set the Argos project slug (`account/project-name`). It picks the project when you authenticate with a [project token linked to several projects](../learn/account-and-access/project-tokens.md#use-a-token-linked-to-several-projects), and disambiguates [tokenless authentication](../learn/integrations/github-actions-authentication.md#tokenless-authentication) when multiple Argos projects are linked to the same repository. `finalize`, `skip`, `deploy` and `baseline download` take it too: ```bash argos upload ./screenshots --project my-account/my-project @@ -301,7 +303,7 @@ ARGOS_TOKEN= argos baseline download -o ./baseline Failure screenshots are left out, because Argos never compares them. Only the latest 1,000 builds with that name on the branch are searched; when none of them is eligible, the command fails with "No baseline found". -`baseline download` only accepts a project token, from `--token` or `ARGOS_TOKEN`, and downloads that token's own project, so it has no `--project` flag. It rejects personal access tokens, including the one `argos login` stores. +`baseline download` only accepts a project token, from `--token` or `ARGOS_TOKEN`, and downloads that token's project. With a token linked to several projects, name the project with `--project owner/project` or `ARGOS_PROJECT`. It rejects personal access tokens, including the one `argos login` stores. Both commands write to a directory that is empty or doesn't exist yet. If it holds anything, they fail without writing a file. Files are laid out by snapshot name, so `chromium/home.png` keeps its folder, and screenshots uploaded from a directory with `argos upload` come back under the same paths, ready to upload again under the same names: @@ -393,6 +395,16 @@ argos project deployments --project team/project --environment production --json argos project domain set acme-web.argos-ci.live --project team/project ``` +`project token` creates, lists and revokes the [project tokens](../learn/account-and-access/project-tokens.md) CI authenticates with. To rotate one without downtime, create its replacement, update the CI secret, then revoke the old token once its last used date stops moving: + +```bash +argos project token create --project team/project --name "GitHub Actions" --permissions builds:write,deployments:write --expires-in 90 +argos project token list --project team/project --json +argos project token revoke --project team/project +``` + +`create` prints the token once; with `--json`, it is in the `token` field. Unlike the dashboard, the CLI gives a new token every permission and no expiration unless you pass `--permissions` (comma-separated, among `builds:write`, `deployments:write`, `projects:read`, `media:read` and `media:write`) and `--expires-in ` or `--expire-at `. Listing takes the reviewer role on the project; creating and revoking take the administrator role. + ### Automation rules `automation` manages the [automation rules](../learn/review-workflow/automations.md) that run when a build event matches. Rules are never deleted — deactivating one keeps its run history, which is what tells you why something fired: @@ -461,6 +473,14 @@ argos account domain remove acme.com --account my-team Removing a domain only stops new sign-ups from joining — members who already joined through it stay. `account update --default-user-level ` sets the role given to everyone who joins through the invite link or a verified domain. +`account project-token` manages every project token of the account, including the ones linked to several projects. `--projects` takes project names without the account, and CI using a token linked to several projects must set `ARGOS_PROJECT`: + +```bash +argos account project-token create --account my-team --projects web,docs --name "Monorepo CI" --permissions builds:write,deployments:write --expires-in 90 +argos account project-token list --account my-team --json +argos account project-token revoke --account my-team +``` + Every command in this section needs a [personal access token](#project-tokens-and-personal-access-tokens) with administrator rights on the team, and takes the account from `--account ` or `ARGOS_ACCOUNT`. ### Paginated lists From 6eda81f5c61221d93eedc7b2793072711e8bbc1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Greg=20Berg=C3=A9?= Date: Mon, 9 Nov 2026 09:18:13 +0100 Subject: [PATCH 3/3] docs(tokens): match the API defaults from argos#2747 review fixes argos-ci/argos#2747 (749192a65) changed what the docs describe: - Creating a token through the API or the CLI without `permissions` now grants `builds:write` and `deployments:write`, not every permission. The CLI examples drop the now-redundant `--permissions`. - `expireAt` is required on the REST create endpoints (`null` for a token that never expires). The CLI still sends `null` by default. - The Upload from CI preset lets CI upload builds and deployments, but not media, instead of covering everything CI needs. - A token linked to a single project ignores ARGOS_PROJECT instead of rejecting a mismatched one with a 401. Co-Authored-By: Claude Opus 5.5 --- docs/learn/account-and-access/project-tokens.md | 10 ++++++---- .../how-to-guides/ci-pipelines/run-argos-in-ci.md | 2 +- .../sdks-reference/argos-command-line-interface-cli.md | 6 +++--- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/learn/account-and-access/project-tokens.md b/docs/learn/account-and-access/project-tokens.md index a4d9a7c6..47d8d3e6 100644 --- a/docs/learn/account-and-access/project-tokens.md +++ b/docs/learn/account-and-access/project-tokens.md @@ -52,7 +52,7 @@ Enter a **Token name** that says where the token is used, such as "GitHub Action ### Choose its permissions and expiration -The defaults, **Upload from CI** and **90 days**, are what CI needs to upload builds and deployments. See [Permissions](#permissions) and [Expiration](#expiration) to change them. +The defaults, **Upload from CI** and **90 days**, let CI upload builds and deployments, but not media. See [Permissions](#permissions) and [Expiration](#expiration) to change them. {% endstep %} {% step %} @@ -71,7 +71,7 @@ When you create a token, choose a preset, or **Advanced** to tick individual per | Preset | Permissions | Use it to | | ---------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- | -| **Upload from CI** (default) | `builds:write`, `deployments:write` | Upload builds and deployments from CI. | +| **Upload from CI** (default) | `builds:write`, `deployments:write` | Upload builds and deployments from CI, but not media. | | **Read only** | `projects:read`, `media:read` | Read builds, screenshot diffs, tests, deployments and media, for example with the [Argos CLI](../../sdks-reference/argos-command-line-interface-cli.md). | | **Full access** | All five permissions | Upload builds and deployments, read projects, and upload or delete media. | | **Advanced** | The ones you tick | Combine permissions yourself. | @@ -149,7 +149,7 @@ env: ``` {% endcode %} -Without it, the upload fails with "This project token is linked to several projects. Pass `project` as `owner/project` (`ARGOS_PROJECT` in the SDK) to choose one." A token linked to a single project doesn't need `ARGOS_PROJECT`; if you set it anyway, it must name that project, or the upload fails with a `401` error. +Without it, the upload fails with "This project token is linked to several projects. Pass `project` as `owner/project` (`ARGOS_PROJECT` in the SDK) to choose one." A token linked to a single project doesn't need `ARGOS_PROJECT`, and ignores it if it is set. When you [transfer a project](../billing-and-subscription/how-to-subscribe.md#transfer-your-projects) to another account, the tokens linked only to that project move with it. A token linked to other projects too stays with the former account and stops working for the transferred project. @@ -172,6 +172,8 @@ The [Argos CLI](../../sdks-reference/argos-command-line-interface-cli.md#configu | `POST /accounts/{accountSlug}/project-tokens` | Creates a token linked to the listed `projects`. | Administrator of the account, or of every listed project. | | `DELETE /accounts/{accountSlug}/project-tokens/{tokenId}` | Revokes a token of the account. | Administrator of the account, or of every project the token is linked to. | -The token's value is only in the response to its creation, in the `token` field. Through the API and the CLI, a token gets every permission unless you pass `permissions`, and never expires unless you pass `expireAt` (`--expires-in` or `--expire-at` in the CLI): set both. +The create endpoints take a `name`, an optional `permissions` list, and a required `expireAt`: an ISO 8601 date, or `null` for a token that never expires. Without `permissions`, the token gets `builds:write` and `deployments:write`, like **Upload from CI**. The token's value is only in the response to its creation, in the `token` field. + +The CLI sends `expireAt: null` unless you pass `--expires-in ` or `--expire-at `, so its tokens never expire by default: pass one of them. The [Argos MCP server](../../agents/mcp-server.md) exposes the same operations as tools, so an AI agent can create, list and revoke project tokens with the permissions you grant it. diff --git a/docs/learn/how-to-guides/ci-pipelines/run-argos-in-ci.md b/docs/learn/how-to-guides/ci-pipelines/run-argos-in-ci.md index 742def76..e8faafe7 100644 --- a/docs/learn/how-to-guides/ci-pipelines/run-argos-in-ci.md +++ b/docs/learn/how-to-guides/ci-pipelines/run-argos-in-ci.md @@ -17,7 +17,7 @@ Commit statuses and pull request comments come from the Argos [GitHub](../../int ### Project token -A project administrator creates the token in the project's **Settings → Authentication**: on the **Project tokens** card, select **Create token**. The default permissions, **Upload from CI**, cover builds and deployments. Argos shows the token only once, so copy it into your CI secret right away. A token linked to several projects is created in **Team Settings → Tokens**, and CI then also needs `ARGOS_PROJECT` set to `owner/project`. +A project administrator creates the token in the project's **Settings → Authentication**: on the **Project tokens** card, select **Create token**. The default permissions, **Upload from CI**, let CI upload builds and deployments, but not media. Argos shows the token only once, so copy it into your CI secret right away. A token linked to several projects is created in **Team Settings → Tokens**, and CI then also needs `ARGOS_PROJECT` set to `owner/project`. A project can have several tokens, so you can give each CI its own, and replace one without downtime: create the replacement, update the CI secret, then revoke the old token once its **Last used** date stops moving. See [Project tokens](../../account-and-access/project-tokens.md) for permissions, expiration, and rotation. diff --git a/docs/sdks-reference/argos-command-line-interface-cli.md b/docs/sdks-reference/argos-command-line-interface-cli.md index 3390aa4d..b94307c2 100644 --- a/docs/sdks-reference/argos-command-line-interface-cli.md +++ b/docs/sdks-reference/argos-command-line-interface-cli.md @@ -398,12 +398,12 @@ argos project domain set acme-web.argos-ci.live --project team/project `project token` creates, lists and revokes the [project tokens](../learn/account-and-access/project-tokens.md) CI authenticates with. To rotate one without downtime, create its replacement, update the CI secret, then revoke the old token once its last used date stops moving: ```bash -argos project token create --project team/project --name "GitHub Actions" --permissions builds:write,deployments:write --expires-in 90 +argos project token create --project team/project --name "GitHub Actions" --expires-in 90 argos project token list --project team/project --json argos project token revoke --project team/project ``` -`create` prints the token once; with `--json`, it is in the `token` field. Unlike the dashboard, the CLI gives a new token every permission and no expiration unless you pass `--permissions` (comma-separated, among `builds:write`, `deployments:write`, `projects:read`, `media:read` and `media:write`) and `--expires-in ` or `--expire-at `. Listing takes the reviewer role on the project; creating and revoking take the administrator role. +`create` prints the token once; with `--json`, it is in the `token` field. Without `--permissions`, a new token can upload builds and deployments (`builds:write` and `deployments:write`), like the dashboard's **Upload from CI**; pass a comma-separated list among `builds:write`, `deployments:write`, `projects:read`, `media:read` and `media:write` to change that. Unlike the dashboard, the CLI creates a token that never expires unless you pass `--expires-in ` or `--expire-at `. Listing takes the reviewer role on the project; creating and revoking take the administrator role. ### Automation rules @@ -476,7 +476,7 @@ Removing a domain only stops new sign-ups from joining — members who already j `account project-token` manages every project token of the account, including the ones linked to several projects. `--projects` takes project names without the account, and CI using a token linked to several projects must set `ARGOS_PROJECT`: ```bash -argos account project-token create --account my-team --projects web,docs --name "Monorepo CI" --permissions builds:write,deployments:write --expires-in 90 +argos account project-token create --account my-team --projects web,docs --name "Monorepo CI" --expires-in 90 argos account project-token list --account my-team --json argos account project-token revoke --account my-team ```