Add Grant

Skill: Add a user grant

Turn an access request into a reviewable Pulumi change. Every human principal is KMS-encrypted, including IAP viewers on Cloud Run services. The change is never applied here — a second person runs the review-grant skill, merges, and runs pulumi up.

Read first:

• infra/pulumi/README.md — the marin-iac stacks, the KMS key, and the pulumi up prerequisites.
• infra/pulumi/src/iac/gcp/iam_data.yaml header — why human user: principals are encrypted and this file is public.

Grant surfaces

Decide which one the request needs before editing anything. A single request can touch both.

1. Shared project / resource GCP IAM — a role on the hai-gcp-models project, the KMS key, a Secret Manager secret, a GCS bucket, an Artifact Registry repo, or a service account (who may impersonate it). Lives in infra/pulumi/src/iac/gcp/iam_data.yaml, applied by the marin stack in infra/pulumi. Each human user:<email> principal is KMS-encrypted once in the principals registry; grants reference its opaque human-NNN ID. Service accounts, groups, and domains stay plain strings.

2. Deploy-target IAM — runtime, secret, repository, KMS, and IAP grants for Echo, EvalDash, Grafana, or Loom. Lives in that target's Python module under infra/pulumi/src/iac/gcp/ and is composed into the marin stack. Human grants reference the encrypted principal registry by opaque ID.

If you are unsure which surface a request means (e.g. "give Alice access to eval results" could be an IAP viewer on evaldash, a roles/storage.objectViewer grant on the record bucket, or both), ask before editing.

Collect the request

You need, per grant:

• Principal — an email for a person, or a serviceAccount:/group:/domain: member for automation. Only personal emails get encrypted.
• What they need access to — the specific resource, stated as a capability ("read the eval record bucket", "impersonate the ray autoscaler SA") rather than a raw role when the requester does not know GCP roles.
• Why / for how long — a one-line justification. If the access is temporary, note it; GcpIamCondition can scope a grant with a CEL expiry, but prefer a follow-up removal PR unless the requester asks for an expiry.

Translate a capability into the narrowest role that satisfies it. Reuse a role already present in the relevant shared or deploy-target declaration for the same resource class before reaching for a broader built-in role. If the request is vague or over-broad, ask for specifics instead of guessing — an IAM grant is hard to walk back once applied.

Running against a GitHub issue

When invoked to respond to an issue rather than a local prompt:

• Fetch it with gh issue view <n> --repo marin-community/marin --json title,body,comments.
• If the issue is missing a principal, the target resource, or a justification, do not guess — post one comment (prefixed 🤖) listing exactly what you need, and stop. Do not open a half-specified PR.
• If the request is complete, build the change and open a PR (below), then comment on the issue linking the PR.

Register and grant the principal

For project-level roles, update the principal registry and every requested role in one command:

uv run --package marin-iac --extra deploy \
  python infra/pulumi/iam_principal.py grant alice@openathena.ai \
    --project-role roles/logging.viewer \
    --project-role roles/monitoring.viewer

The command decrypts existing registry entries locally to find and reuse the person's opaque ID. It encrypts and registers the email once when the person is new, then writes deterministic YAML. Encryption and lookup need roles/cloudkms.cryptoKeyEncrypterDecrypter on the marin-iac key (the same access pulumi up needs).

For a KMS key, secret, bucket, Artifact Registry repository, or service-account grant, register the principal first:

uv run --package marin-iac --extra deploy \
  python infra/pulumi/iam_principal.py register alice@openathena.ai

The command prints the existing or new human-NNN ID. Add principal: human-NNN to a shared resource grant or principals["human-NNN"] to a deploy-target module. Never write a personal email in plaintext into either declaration, a commit message, or the PR body — the repo is public.

Make the edit

Project / resource IAM — update iam_data.yaml:

• Find the grant for the target role and resource, or add one. Project roles go in project_grants; a bucket/secret/repo/service-account grant goes under that resource's entry in buckets / secrets / artifact_repositories / service_accounts (add the resource entry if it is not there yet).
• Project-role requests are already complete after iam_principal.py grant. For other resource grants, add the registered principal: human-NNN reference. Add a plain member string for service accounts, groups, domains, workload identities, or other automation.

Deploy-target or IAP grant — add the registered principals["human-NNN"] reference to the target's iam_grants() declaration under infra/pulumi/src/iac/gcp/. Plain service-account, group, and domain members can be added directly.

Verify and open the PR

• ./infra/pre-commit.py --files <edited files> (or --changed-files), fixing anything it reports. git add a new file before linting so it is scoped in.

• Do not run pulumi preview/up — a local preview decrypts and prints the real emails, and applying is the reviewer's step. CI runs a redacted preview on the PR.

• Follow the commit skill to commit, push, and open the PR against main. Add the agent-generated label. Title the PR for the capability, not the person: [iac] Grant eval-bucket read to a new operator, never the email. The body states the resource, the role, and the one-line justification — no personal emails. Note in the body that a reviewer should run review-grant, then pulumi up on the marin stack.

• Assign the PR to the grant approvers so one of them picks up review-grant:

  gh pr edit <n> --repo marin-community/marin \
    --add-assignee yonromai,ravwojdyla,rjpower