# Teams and Access

> Organize apps by team, grant per-app and per-pipeline roles, and keep build-failure noise off the people who don't need it.

Watasu has three layers of access. Each one stacks on the others, and most teams only need to think about one or two.

```
Team role           ─ admin or member
   ↓
Pipeline role       ─ inherited by every app in the pipeline
   ↓
App role            ─ exact permissions on a single app
```

## Team roles

A team is the unit that owns apps, add-ons, pipelines, and the bill. Every user in a team has one of two roles:

| Team role  | What it grants                                                                                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Admin**  | Full access to every app, pipeline, and add-on the team owns. Can add and remove members, manage billing, and connect GitHub. Implicitly a Maintainer on every team app. |
| **Member** | Belongs to the team. Can create new apps in the team. Has **no implicit access** to existing apps — access must be granted per app or per pipeline.                      |

The team owner is always an Admin and can't be demoted.

> **Member ≠ visibility into every app.** Adding someone as a team member lets them create their own apps in the team. To let them see, deploy, or operate an existing app you grant them an app or pipeline role explicitly. This is intentional: it stops a junior added to the team from auto-receiving build-failure emails for every app the team owns.

## App and pipeline roles

The same four named roles exist on apps and on pipelines. Higher tiers strictly include the lower ones.

| Role           | What you can do                                                                                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Viewer**     | Read-only: open the app in the dashboard, view logs, metrics, and releases, `git pull`                                         |
| **Deployer**   | Everything in Viewer, plus push code and trigger builds                                                                        |
| **Operator**   | Everything in Deployer, plus restart processes, scale, run one-off commands, view runtime details, reboot add-ons              |
| **Maintainer** | Everything in Operator, plus edit config vars, deploy settings, custom domains, add-on attachments, and the access list itself |

Pick the lowest role that lets the person do their actual job. Tightening later is harder than starting tight.

Under the hood these roles are permission sets — `view`, `deploy`, `operate`, `manage` — and the CLI grants them as a list:

```bash
watasu access:add dev@example.com --app my-app --permissions view,deploy
```

### App-level role

Granted on a single app. Useful when one team owns several apps and you want to give someone deploy rights on one without showing them the others.

### Self-join and locking

Team members can add themselves to an unlocked team app with `watasu apps:join --app <app>`, which grants Viewer access. If an app shouldn't be self-joinable (production, anything sensitive), lock it:

```bash
watasu apps:lock --app my-app
```

Locked apps require an explicit grant from someone with Maintainer access. `watasu apps:unlock` reverses it.

### Pipeline-level role

Granted on a pipeline. **Inherited by every app attached to that pipeline** (staging, production) AND by every ephemeral review app spawned from it. Useful for the common case: "this engineer ships everything in the `watasu-web` pipeline" — one grant covers staging, production, and every PR review app.

When both an app role and a pipeline role apply, the user gets the **union** of the two permission sets. So a Pipeline Operator with an explicit app-level Maintainer grant on a single staging app is a Maintainer on that staging app and an Operator on everything else in the pipeline.

## How notifications follow access

Build, deploy, and rollback events email the people who can actually act on them:

* **Team Admins** of the app's team
* **Pipeline-level Deployers, Operators, and Maintainers** (when the app belongs to a pipeline)
* **App-level Deployers, Operators, and Maintainers** on that specific app

Pure team Members and Viewer-tier collaborators are not paged about builds — they don't need that noise. Access changes (someone added or removed) and add-on attachments still notify everyone who can see the app, so material changes don't go silent.

## A worked example

A team has three engineers and one pipeline `watasu-web` with two attached apps (`watasu-web-staging`, `watasu-web`) and an active PR review app `pr-1348`:

* **Asha** is the team Admin → Maintainer on every app, gets every email.
* **Ben** is a team Member with **Pipeline Operator** on `watasu-web` → can deploy and operate staging, production, and the PR review app. Gets build-failure emails for all three.
* **Carol** is a team Member with **App Viewer** on `watasu-web-staging` only → can see staging logs/metrics, can't deploy. Doesn't get build emails.

When the PR review app's build fails, Asha and Ben are emailed. Carol is not. The email's subject reads `Build #6 failed on watasu-web (PR #1348 review app)` — never the cryptic temp app name — so the recipients know the parent context at a glance.

## Hygiene

* Grant **Deployer** to people who actually deploy. Don't default to Maintainer.
* Use **pipeline-level** access when one person handles a service end-to-end. It's one grant per service instead of one per environment.
* Review access on every team change — someone joining means thinking about what they need; someone leaving means revoking everything they had.
* Keep one person per login. Add the person; don't share the credential.

[View this page on the web](https://docs.watasu.io/admin/teams-and-access/)