From 5fe165a746cbe38c810d7c58ca9b593aabaf9e35 Mon Sep 17 00:00:00 2001 From: Matthew Helmke Date: Tue, 20 Oct 2026 10:35:02 -0500 Subject: [PATCH] Drop the viewer step for sandbox.user teammates The sandbox.user role now includes groups.list, so chainctl finds the organization by name without viewer. A live test on 2026-10-20 showed it twice: as a static identity bound only to sandbox.user, and as a real teammate who accepted a sandbox.user invite. Both ran chainctl checks list and chainctl develop list with --parent set to the organization's name, and both exited 0, the same as with its ID. - Set up page: "Add a teammate" is now two steps, an invite with --role sandbox.user and its acceptance, because accepting the invite grants the role. The roles table drops the viewer row and gains a column for what each role allows inside a session, plus mcp.tool_user, which the Chainguard MCP servers need there. The Starter steps point at the new step 1. - The checks reference, "Inspect and run checks," Checks troubleshooting, the develop reference, and Workspaces getting started no longer say sandbox.user needs viewer. - Capabilities reference: sandbox.user can list apk and groups. Co-Authored-By: Claude Opus 5.5 --- .../checks/chainctl-checks-reference.md | 4 +-- .../checks/inspect-and-run-checks.md | 4 +-- content/chainguard/checks/troubleshooting.md | 4 +-- .../workspaces/chainctl-develop-reference.md | 6 ++-- .../chainguard/workspaces/getting-started.md | 4 +-- .../checks-and-workspaces/set-up.md | 34 +++++++------------ .../capabilities-reference.md | 6 ++-- 7 files changed, 25 insertions(+), 37 deletions(-) diff --git a/content/chainguard/checks/chainctl-checks-reference.md b/content/chainguard/checks/chainctl-checks-reference.md index ff201844e3..639667f739 100644 --- a/content/chainguard/checks/chainctl-checks-reference.md +++ b/content/chainguard/checks/chainctl-checks-reference.md @@ -4,7 +4,7 @@ linktitle: "chainctl checks reference" description: "Reference for the chainctl checks commands that inspect pull request runs, start and rerun checks, summarize check history, and validate your Chainguard Checks configuration." type: "article" date: 2026-10-12T00:00:00+00:00 -lastmod: 2026-10-15T12:09:53+00:00 +lastmod: 2026-10-20T15:35:02+00:00 draft: false tags: ["Chainguard Checks", "chainctl", "Reference"] images: [] @@ -52,7 +52,7 @@ If you created a Starter organization with `chainctl develop init`, you have the The `validate`, `explain`, and `migrate --dry` commands read only your local checkout, so they don't need a Chainguard account or network access. -The commands that need a role take `--parent` with the name or ID of your Chainguard organization. To use the name, you also need a role that can see the organization, such as `viewer`. With `sandbox.user` alone, pass the organization's ID. Without `--parent`, `chainctl` uses the `CHAINCTL_SANDBOX_GROUP` environment variable, then the `default.group` value in your `chainctl` configuration. If neither is set, it asks you to choose an organization. +The commands that need a role take `--parent` with the name or ID of your Chainguard organization. Without `--parent`, `chainctl` uses the `CHAINCTL_SANDBOX_GROUP` environment variable, then the `default.group` value in your `chainctl` configuration. If neither is set, it asks you to choose an organization. ## Name a run {#name-a-run} diff --git a/content/chainguard/checks/inspect-and-run-checks.md b/content/chainguard/checks/inspect-and-run-checks.md index 9f76aefb14..301986befb 100644 --- a/content/chainguard/checks/inspect-and-run-checks.md +++ b/content/chainguard/checks/inspect-and-run-checks.md @@ -4,7 +4,7 @@ linktitle: "Inspect and run checks" description: "Read a pull request's Chainguard Checks results and logs from your terminal, run checks on a pushed commit without a pull request, and find the checks that take the most time or fail most often." type: "article" date: 2026-10-12T00:00:00+00:00 -lastmod: 2026-10-15T12:09:53+00:00 +lastmod: 2026-10-20T15:35:02+00:00 draft: false tags: ["Chainguard Checks", "chainctl", "Procedural"] images: [] @@ -17,7 +17,7 @@ weight: 55 The `chainctl checks` commands read your checks' results from your terminal, so you or a coding agent can find out why a check failed without opening GitHub. This page explains how to inspect a pull request's runs, how to run checks on a pushed commit without opening a pull request, and how to find the checks that take the most time or fail most often. For every command and flag, refer to the [`chainctl checks` command reference](/chainguard/checks/chainctl-checks-reference/). -These commands need a role in your Chainguard organization, as described in [The Details link or a chainctl checks command says you don't have access](/chainguard/checks/troubleshooting/#the-details-link-or-a-chainctl-checks-command-says-you-dont-have-access). To pass your organization's name to `--parent`, rather than its ID, you also need a role that can see the organization, such as `viewer`. +These commands need a role in your Chainguard organization, as described in [The Details link or a chainctl checks command says you don't have access](/chainguard/checks/troubleshooting/#the-details-link-or-a-chainctl-checks-command-says-you-dont-have-access). ## Inspect pull request runs {#inspect-pull-request-runs} diff --git a/content/chainguard/checks/troubleshooting.md b/content/chainguard/checks/troubleshooting.md index 9219ec4f62..1069bfbe51 100644 --- a/content/chainguard/checks/troubleshooting.md +++ b/content/chainguard/checks/troubleshooting.md @@ -4,7 +4,7 @@ linktitle: "Troubleshooting" description: "Fix common problems with Chainguard Checks, including pull requests that get no checks, refused configurations, failed runs, checks that couldn't run, network errors, missing tools, and unused caches." type: "article" date: 2026-10-08T00:00:00+00:00 -lastmod: 2026-10-15T12:09:53+00:00 +lastmod: 2026-10-20T15:35:02+00:00 draft: false tags: ["Chainguard Checks", "Troubleshooting"] images: [] @@ -207,8 +207,6 @@ For a run you started with [`chainctl checks run`](/chainguard/checks/chainctl-c The **Details** link on a check opens the run on a page that Chainguard hosts, where you sign in with your Chainguard account. To open the run page, or to read or rerun runs with `chainctl checks` commands such as `status`, `logs`, and `rerun`, you need the `owner` or `sandbox.user` role in the Chainguard organization linked to the repository's GitHub account. Without one of these roles, `chainctl checks` fails with `permission denied`. -To pass your organization's name to `--parent`, you also need a role that can see the organization, such as `viewer`. With `sandbox.user` alone, `chainctl` can't find your organization by its name, so pass the organization's ID instead. - To get these roles, ask an owner of your organization, as described in [Give teammates access](/get-started/checks-and-workspaces/set-up/#give-teammates-access). During the beta, if you created a Starter organization with `chainctl develop init`, you have the `limited_owner` role instead, which can't open the run page or read runs, and you can't grant the `sandbox.user` role. In that case, do the following: diff --git a/content/chainguard/workspaces/chainctl-develop-reference.md b/content/chainguard/workspaces/chainctl-develop-reference.md index f592dfb727..4edae53942 100644 --- a/content/chainguard/workspaces/chainctl-develop-reference.md +++ b/content/chainguard/workspaces/chainctl-develop-reference.md @@ -4,7 +4,7 @@ linktitle: "chainctl develop reference" description: "Reference for the chainctl develop commands that open and manage Chainguard Workspaces sessions, with their flags, output formats, exit codes, and the roles they need." type: "article" date: 2026-10-12T00:00:00+00:00 -lastmod: 2026-10-15T12:09:53+00:00 +lastmod: 2026-10-20T15:35:02+00:00 draft: false tags: ["Chainguard Workspaces", "chainctl", "Reference"] images: [] @@ -285,11 +285,11 @@ What you can do with `chainctl develop` depends on your role in the session's or | Commands | Roles | | -------- | ----- | -| `chainctl develop`, `list`, `rename`, `delete`, `check`, `creds`, `github`, and `policy describe` | `owner`, `limited_owner`, or `sandbox.user` together with a role that includes `groups.list`, such as `viewer` | +| `chainctl develop`, `list`, `rename`, `delete`, `check`, `creds`, `github`, and `policy describe` | `owner`, `limited_owner`, or `sandbox.user` | | `accept-terms` | `owner` or `limited_owner` | | `list --all` and `policy set` | `owner` | -The `limited_owner` role is the one that `chainctl develop init` gives the person who creates a Starter organization. No one in a Starter organization has the `owner` role, so no one there can run `list --all` or `policy set`. On their own, other roles, such as `editor` and `viewer`, can't open or manage sessions. A teammate with `sandbox.user` also needs the `viewer` role, as described in [Give teammates access](/get-started/checks-and-workspaces/set-up/#give-teammates-access). To run `chainctl develop init --parent` on an organization you already belong to, you need the `owner` or `limited_owner` role in it. An organization owner can grant the `sandbox.user` role with a role-binding, as described in [Overview of roles and role-bindings](/platform/administration/iam-organizations/roles-role-bindings/roles-role-bindings/). +The `limited_owner` role is the one that `chainctl develop init` gives the person who creates a Starter organization. No one in a Starter organization has the `owner` role, so no one there can run `list --all` or `policy set`. On their own, other roles, such as `editor` and `viewer`, can't open or manage sessions. To run `chainctl develop init --parent` on an organization you already belong to, you need the `owner` or `limited_owner` role in it. An organization owner can grant the `sandbox.user` role with an invite, as described in [Give teammates access](/get-started/checks-and-workspaces/set-up/#give-teammates-access). In a session, your role also limits what your Chainguard identity can do. The `limited_owner` role doesn't include `mcp.tool.call` or `sandbox.run.list`, so the Chainguard MCP servers and the `chainctl checks` commands that look up a run don't work for it. Refer to [MCP servers in a session](/chainguard/workspaces/coding-agents/#mcp-servers-in-a-session) and [Your Chainguard identity in a session](/chainguard/workspaces/credentials/#your-chainguard-identity-in-a-session). diff --git a/content/chainguard/workspaces/getting-started.md b/content/chainguard/workspaces/getting-started.md index 32d799a6fa..3b0ad004fa 100644 --- a/content/chainguard/workspaces/getting-started.md +++ b/content/chainguard/workspaces/getting-started.md @@ -4,7 +4,7 @@ linktitle: "Getting started" description: "Sign up for Chainguard Workspaces, open your first development session, and learn how to detach from it and return." type: "article" date: 2026-10-08T00:00:00+00:00 -lastmod: 2026-10-15T12:09:53+00:00 +lastmod: 2026-10-20T15:35:02+00:00 draft: false tags: ["Chainguard Workspaces", "Getting Started", "Procedural"] images: [] @@ -94,7 +94,7 @@ The `delete` command asks you to confirm, then destroys the session's VM and its -Each teammate opens and manages their own sessions, which count toward your organization's [limits](/chainguard/workspaces/overview/#availability-and-limits). To open sessions, a teammate needs the `owner` or `limited_owner` role, or the `sandbox.user` role together with `viewer`. To give them one, refer to [Give teammates access](/get-started/checks-and-workspaces/set-up/#give-teammates-access). +Each teammate opens and manages their own sessions, which count toward your organization's [limits](/chainguard/workspaces/overview/#availability-and-limits). To open sessions, a teammate needs the `owner` or `limited_owner` role, or the `sandbox.user` role. To give them one, refer to [Give teammates access](/get-started/checks-and-workspaces/set-up/#give-teammates-access). ## Next steps diff --git a/content/get-started/checks-and-workspaces/set-up.md b/content/get-started/checks-and-workspaces/set-up.md index cf17ed8968..f4d6224d61 100644 --- a/content/get-started/checks-and-workspaces/set-up.md +++ b/content/get-started/checks-and-workspaces/set-up.md @@ -4,7 +4,7 @@ linktitle: "Set up Checks and Workspaces" description: "How Chainguard Checks and Chainguard Workspaces work together, and how to sign up for both with chainctl develop init and give teammates access." type: "article" date: 2026-10-13T00:00:00+00:00 -lastmod: 2026-10-13T18:50:45+00:00 +lastmod: 2026-10-20T15:35:02+00:00 draft: false tags: ["Chainguard Checks", "Chainguard Workspaces", "Getting Started", "Procedural"] images: [] @@ -135,22 +135,22 @@ If your GitHub account isn't linked to the organization yet, link it as describe Your teammates don't need a Chainguard account to get checks on their pull requests or to read the results on GitHub. A teammate needs a role in your Chainguard organization to open the Chainguard Checks run page, to use `chainctl checks` commands such as `status` and `rerun`, or to open Workspaces sessions. Each teammate opens and manages their own sessions, which count toward your organization's [limits](/chainguard/workspaces/overview/#availability-and-limits). -| Role | In Chainguard Checks | In Chainguard Workspaces | -| ---- | -------------------- | ------------------------ | -| `viewer` | Lets `chainctl` find your organization by name, which `--parent $ORGANIZATION` needs. | Lets `chainctl develop` find your organization by name. | -| `sandbox.user` | Opens the run page, and reads, reruns, and cancels runs with `chainctl checks`. | Opens and manages the teammate's own sessions, and runs checks in them. | -| `limited_owner` | Starts runs with `chainctl checks run`, but can't open the run page or read runs. | Opens sessions. Also manages your organization's billing and invites or removes members. | +| Role | In Chainguard Checks | In Chainguard Workspaces | Inside a session | +| ---- | -------------------- | ------------------------ | ---------------- | +| `sandbox.user` | Opens the run page, and reads, reruns, and cancels runs with `chainctl checks`. | Opens and manages the teammate's own sessions, and runs checks in them. | `chainctl checks` commands work as the teammate. The Chainguard MCP servers don't, because the role doesn't include the `mcp.tool.call` capability. | +| `limited_owner` | Starts runs with `chainctl checks run`, but can't open the run page or read runs. | Opens sessions. Also manages your organization's billing and invites or removes members. | Neither the Chainguard MCP servers nor the `chainctl checks` commands that look up a run, such as `status` and `logs`, work. | +| `mcp.tool_user` | Nothing. | Nothing. | Adds `mcp.tool.call`, so the Chainguard MCP servers work. | -A teammate who uses `sandbox.user` also needs `viewer`. For more about roles, refer to [Overview of roles and role-bindings](/platform/administration/iam-organizations/roles-role-bindings/roles-role-bindings/). +Inside a session, a teammate's Chainguard identity can't do more than their role allows, as described in [Your Chainguard identity in a session](/chainguard/workspaces/credentials/#your-chainguard-identity-in-a-session). For more about roles, refer to [Overview of roles and role-bindings](/platform/administration/iam-organizations/roles-role-bindings/roles-role-bindings/). ### Add a teammate {#add-a-teammate} -In a Starter organization, the steps differ, as described in [Add a teammate to a Starter organization](#add-a-teammate-to-a-starter-organization). If you have the `owner` role in your organization, invite your teammate and grant them the `sandbox.user` role as follows. Replace `$ORGANIZATION` with the name of your Chainguard organization: +In a Starter organization, the steps differ, as described in [Add a teammate to a Starter organization](#add-a-teammate-to-a-starter-organization). If you have the `owner` role in your organization, invite your teammate with the `sandbox.user` role as follows. Replace `$ORGANIZATION` with the name of your Chainguard organization: -1. Create an invite for your teammate with the `viewer` role. Your teammate needs it as well as `sandbox.user`, because `sandbox.user` alone doesn't let `chainctl` find your organization. Replace `$EMAIL` with your teammate's email address: +1. Create an invite for your teammate with the `sandbox.user` role. Replace `$EMAIL` with your teammate's email address: ```shell - chainctl iam invite create $ORGANIZATION --role viewer --email $EMAIL + chainctl iam invite create $ORGANIZATION --role sandbox.user --email $EMAIL ``` 2. Send your teammate the invite code that the command prints. Your teammate accepts the invite by logging in with it, replacing `$INVITE_CODE` with the code: @@ -159,17 +159,7 @@ In a Starter organization, the steps differ, as described in [Add a teammate to chainctl auth login --invite-code $INVITE_CODE ``` -3. After your teammate accepts, list your organization's role-bindings. The output shows each member's identity ID next to their email address: - - ```shell - chainctl iam role-bindings list --parent $ORGANIZATION - ``` - -4. Grant your teammate the `sandbox.user` role, replacing `$IDENTITY_ID` with their identity ID: - - ```shell - chainctl iam role-bindings create --identity $IDENTITY_ID --role sandbox.user --parent $ORGANIZATION - ``` +Accepting the invite grants the role. To let a teammate use the Chainguard MCP servers in sessions, also grant them `mcp.tool_user` with a role-binding, as described in [Overview of roles and role-bindings](/platform/administration/iam-organizations/roles-role-bindings/roles-role-bindings/). Your teammate can then install `chainctl`, as described in [Install or update chainctl](#install-or-update-chainctl), and open a session, as described in [Get started with Chainguard Workspaces](/chainguard/workspaces/getting-started/#step-2-open-a-session). @@ -177,7 +167,7 @@ Your teammate can then install `chainctl`, as described in [Install or update ch If you created your organization with `chainctl develop init`, it's a Starter organization, and you have the `limited_owner` role rather than `owner`. You can't create role-bindings for other users, so you can't grant the `sandbox.user` role, and members read Chainguard Checks results on GitHub instead of on the run page. An invite can give only a role whose permissions you also have, and of those roles, only `limited_owner` can open sessions. -To invite a teammate, run steps 1 and 2 of [Add a teammate](#add-a-teammate). To let your teammate open sessions, use `--role limited_owner` instead of `--role viewer` in step 1: +To invite a teammate who can open sessions, follow [Add a teammate](#add-a-teammate), but use `--role limited_owner` instead of `--role sandbox.user` in step 1: ```shell chainctl iam invite create $ORGANIZATION --role limited_owner --email $EMAIL diff --git a/content/platform/administration/iam-organizations/roles-role-bindings/capabilities-reference.md b/content/platform/administration/iam-organizations/roles-role-bindings/capabilities-reference.md index 4ce9788e06..0c3d484346 100644 --- a/content/platform/administration/iam-organizations/roles-role-bindings/capabilities-reference.md +++ b/content/platform/administration/iam-organizations/roles-role-bindings/capabilities-reference.md @@ -7,7 +7,7 @@ lead: "Reference for Chainguard's built-in roles and their specific capabilities description: "A resource documenting the capabilities and permissions of Chainguard's built-in IAM roles." type: "article" date: 2025-08-14T00:00:00Z -lastmod: 2026-10-13T13:55:57+00:00 +lastmod: 2026-10-20T15:35:02+00:00 draft: false tags: ["IAM", "Reference", "Product"] images: [] @@ -83,12 +83,12 @@ The following table maps Chainguard resources to the built-in roles that have pe | `account_associations` | Link cloud provider accounts to organization | | | `actions` | View the [Chainguard Actions](/chainguard/actions/overview/) catalog | | | `advisories` | View [security advisories](/chainguard/containers/security-and-compliance/security-advisories/) for the packages in Chainguard images | | -| `apk` | Manage APK packages in the registry | | +| `apk` | Manage APK packages in the registry | | | `apk.blobs` | Download APK package binary content | | | `billing` | Manage the organization's billing and payment method | | | `build_report` | Access detailed build and scan reports for images and packages | | | `group_invites` | Send and manage invitations to join Chainguard organization | | -| `groups` | Manage organization and hierarchical structures | | +| `groups` | Manage organization and hierarchical structures | | | `guardener.actions` | Have Guardener migrate a repository's GitHub Actions to Chainguard Actions by opening a pull request | | | `guardener.association` | View and manage the GitHub organizations connected through [the Chainguard App](/chainguard/guardener/github/app-connections/) | | | `guardener.dfc` | Convert Dockerfiles to use Chainguard images with [Guardener](/chainguard/guardener/dockerfile-migration/) | |