Skip to main content

MANAGE GRANTS WITH FILES

This guide shows you how to manage authorization grants as YAML files checked into version control.

Create the grants directory

The grants/ directory is created by swamp repo init. If it does not exist, create it at the root of your Swamp repository:

mkdir grants

Write a grant file

Create a YAML file in grants/ with one or more grant definitions. Each file can contain multiple grants under a top-level grants key:

# grants/platform-team.yaml
grants:
  - subject: idp-group:platform-eng
    effect: allow
    actions: [run]
    resource: workflow:@acme/*
  - subject: idp-group:platform-eng
    effect: allow
    actions: [run]
    resource: workflow:@acme/*
    condition: 'tags.env == "staging"'

Use separate files to organize grants by team or concern — for example, platform-team.yaml, compliance.yaml, read-only-users.yaml.

Accepted file extensions are .yaml and .yml. The directory is flat — files in subdirectories are ignored.

Refer to the Grant files reference for every field an entry takes.

Give several subjects the same access

To give a team the same grants without repeating an entry per person, list them under subjects, and list resources under resources:

# grants/release-team.yaml
grants:
  - subjects:
      - user:alice
      - user:bob
    effect: allow
    actions: [run, read]
    resources:
      - workflow:@acme/create-thing
      - workflow:@acme/connect-thing

The entry expands into one grant per subject and resource pair. Replacing repeated single-subject entries with one subjects entry changes no grants when you reload.

If membership changes more often than you want to edit the file, grant a group: subject instead and manage its members with swamp access group. See Manage Groups.

To check a file before a deploy, run swamp serve check-config.

Apply the grants

Run swamp access reload to validate and apply all grant files:

swamp access reload --server wss://swamp.example.com

If any file contains invalid grants, the entire reload is rejected and the current policy remains unchanged.

Refer to the Access Commands reference for full details on reload behavior.

Add more grants

Add new entries to an existing file or create a new file, then reload:

swamp access reload --server wss://swamp.example.com

Remove grants

Delete the grant entry from its file (or delete the entire file), then reload:

swamp access reload --server wss://swamp.example.com

Identify grant sources

The source column in swamp access grant list shows where each grant originated:

swamp access grant list --server wss://swamp.example.com

File-sourced grants appear as file:<filename> (e.g., file:platform-team.yaml). Grants loaded with --grants-dir appear as file:grants-dir/<filename>, and grants loaded with --grants-file as file:grants-file. CLI-created grants appear as method. File grants and CLI grants coexist in the same store.