> For the complete documentation index, see [llms.txt](https://docs.pipekit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pipekit.io/organizations-and-access/rbac/publish-rbac-policy.md).

# Publish RBAC Policy

Manage Pipekit access with an RBAC policy file.

{% hint style="info" %}
Publishing your first policy? Start with [Set Up Multi-tenant RBAC](https://docs.pipekit.io/organizations-and-access/rbac/set-up.md). The first publish switches your organization from basic permissions to multi-tenant RBAC.
{% endhint %}

Use an RBAC policy file to manage Pipekit access as code with [multi-tenant RBAC](https://docs.pipekit.io/organizations-and-access/rbac.md). The policy defines organization-level bindings, workspaces, namespace targets, and workspace-level bindings in a single YAML file.

Publishing a policy replaces the active RBAC configuration. If validation fails, Pipekit rejects the publish and keeps the previously active policy unchanged.

This page walks through the publish workflow. For every command, flag, and validation message, refer to [RBAC Policy](https://docs.pipekit.io/reference/cli/rbac.md) in the CLI reference.

{% hint style="info" %}
Your first publish needs the basic admin permission from the `Users` tab. After that, the account that publishes must hold `orgAdmin` in the active policy.
{% endhint %}

## Create a Policy File

Create a YAML file such as `pipekit-policy.yaml`:

```yaml
schemaVersion: 1

orgBindings:
  - subject: idp:team:platform
    role: orgAdmin
  - subject: user:pipekit-ci@example.com
    role: orgAdmin

workspaces:
  - name: team-foo
    targets:
      - cluster: cluster-prod
        namespace: team-foo-ns
    bindings:
      - subject: idp:team:foo
        role: editor
      - subject: idp:team:foo-leads
        role: workspaceAdmin

  - name: team-bar
    targets:
      - cluster: cluster-prod
        namespace: team-bar-ns
      - cluster: cluster-staging
        namespace: team-bar-staging
    bindings:
      - subject: idp:team:bar
        role: viewer
      - subject: idp:team:support
        role: runner
```

Keys are camelCase. The policy file has three top-level sections:

| Field           | Description                                                             |
| --------------- | ----------------------------------------------------------------------- |
| `schemaVersion` | The RBAC policy schema version. It must be `1`.                         |
| `orgBindings`   | Subjects that receive access across the organization.                   |
| `workspaces`    | Workspace definitions, namespace targets, and workspace-level bindings. |

Each binding names a `subject` and a `role`. A subject is `user:<email>` for one Pipekit user, or `idp:team:<group-name>` for a group your identity provider syncs to Pipekit. Use the group name exactly as it appears on the `Groups` tab under `People & Access`. Names are case-sensitive. A role is `viewer`, `runner`, `editor`, `workspaceAdmin`, or `orgAdmin`. For what each role can do, refer to [Roles](https://docs.pipekit.io/organizations-and-access/rbac.md#roles). Use `orgAdmin` only under `orgBindings`.

Each workspace must have a unique `name`. Pipekit ignores case and surrounding spaces when it compares names, so `Team-A` and `team-a` collide. Each target maps the workspace to an explicit `cluster` and `namespace`. Wildcard namespace targets are not supported, and one workspace at most can claim a given cluster and namespace pair.

## Validate Without Publishing

Use `--dry-run` to validate a policy and see the plan without changing the active configuration:

```bash
pipekit rbac publish --dry-run -f pipekit-policy.yaml
```

The command prints each check it ran, then the changes it would make under `Planning...`, then `(dry-run: no changes made)`. Read the plan before you publish. A workspace that disappears from the file is deleted, and Pipekit revokes the grants under it.

Use dry-run validation in CI so pull requests fail before an invalid policy is merged. The command exits non-zero when the policy is rejected.

## Publish a Policy

Publish the policy with:

```bash
pipekit rbac publish -f pipekit-policy.yaml
```

Pipekit validates the full file against your organization's live state, applies the plan, and creates a new policy version. The output lists the checks, the changes it applied, the new version number, and the previous version.

To check the access each user now has, open `People & Access` on the `Org` page and go to `Users`. For what that tab shows, refer to [Viewing access under a multi-tenant RBAC policy](https://docs.pipekit.io/organizations-and-access/members.md#viewing-access-under-a-multi-tenant-rbac-policy).

## Review Validation Results

Pipekit validates the entire policy before publishing it. Validation errors are returned together so you can fix them in one change.

* An error rejects the whole file. The active policy stays in force.
* A warning never blocks a publish. For example, a binding to an IdP group that does not exist yet is a warning. The binding takes effect once the group appears.

A rejected publish ends with a line that names the version still in force:

```
Active config unchanged (v3 still enforced).
```

For the full list of checks and example messages, refer to [Errors and warnings](https://docs.pipekit.io/reference/cli/rbac.md#errors-and-warnings).

## GitOps Workflow

Store the policy file in the same repository where you manage infrastructure configuration.

```
infra/
  pipekit/
    pipekit-policy.yaml
```

Use this workflow:

1. Open a pull request that changes `pipekit-policy.yaml`.
2. Run `pipekit rbac publish --dry-run -f pipekit-policy.yaml` in CI.
3. Review and merge the pull request.
4. Run `pipekit rbac publish -f pipekit-policy.yaml --git-sha "$GIT_SHA"` after merge.

Passing the Git SHA records the source commit with the published policy version. `pipekit rbac list` shows it later.

CI needs its own Pipekit account:

1. Create a Pipekit user for CI that signs in with a password.
2. Grant it `orgAdmin` with a `user:` binding, as `user:pipekit-ci@example.com` does in the example above.
3. In CI, sign in with `pipekit login -u <username> -p <password>`, as described in [Non-interactive login](https://docs.pipekit.io/reference/cli/advanced.md#non-interactive-login). Store the password as a CI secret.

If a published policy drops that grant, CI can no longer publish, including a fix.

## Roll Back

Revert the Git commit that changed the policy file. When the revert is merged, CI publishes the reverted policy as a new version.

For a fast rollback from the CLI, fetch a previous version and publish it again:

```bash
pipekit rbac get --version 3 | pipekit rbac publish -f -
```

`--version` takes a version number without the `v`. `-f -` reads the policy from stdin.

Rollback creates a new policy version. Policy history remains linear, and previous versions remain available for audit and recovery.

## If You Lock Out Every Org Admin

A published policy can leave nobody who holds `orgAdmin`, for example when every `orgAdmin` grant goes to an empty group. Nobody can then publish a fix with their own account.

* On Pipekit Cloud, email `support@pipekit.io`. Pipekit support restores access to your organization.
* On a self-hosted control plane, sign in with the break glass account. The break glass account is an internal account, so the policy does not restrict it. If you turned off the username and password login box with `login.userPass.enabled`, turn it back on first. Publish a fixed policy, then sign out. For the credentials, refer to [Initial login](https://docs.pipekit.io/self-hosting-pipekit/initial-login.md).
