Roles & Access

Every project controls who can do what through roles. A role is a named set of permissions — read, write, or delete on specific folders or files — that you assign to a person or a HAL device. Roles are created and managed on the project's Settings → Roles page by an organization admin.

The organization owner always has full access to everything in their projects, regardless of roles. Roles are how you grant access to everyone else.

How a permission is written

A permission has three parts:

Part	Values
Resource type	Folder (matches a whole folder) or File (one file)
Path	Where in the project the rule applies
Actions	Any of Read, Write, Delete

Paths are written relative to the project, with no leading slash:

• A folder rule matches everything under that folder by prefix. documents/ covers documents/spec.md, documents/datasheets/part.pdf, and so on.
• A file rule matches one exact path, like documents/readme.md.
• The special folder path * matches everything in the project.

note

Paths never start with a slash. Write documents/, not /documents/.

Project folders

Files in a project are organized into a handful of standard folders. These are the paths you'll usually grant against:

Folder	What lives there
photos/	Photos of the board, bring-up, and assembly
documents/	Datasheets, notes, and markdown write-ups
releases/	Firmware and release artifacts
state-machines/diagrams/	State machine diagrams
state-machines/palette/	Reusable state machine building blocks
todos/	Task files for the project

You can also grant against a subfolder you create yourself, like releases/beta/ or documents/internal/ — any prefix works.

Permissions add up

Permissions are additive: a person gets an action on a path if any rule in their role allows it. There are no "deny" rules.

To give someone broad access with a tighter area inside it, grant the narrower path separately rather than trying to carve out an exception. For example, to let a contractor read all documents but only write to one subfolder:

Resource type	Path	Read	Write	Delete
Folder	documents/	✓
Folder	documents/datasheets/	✓	✓

The first rule grants read across all of documents/; the second adds write on just the datasheets/ subfolder.

warning

Because permissions only ever grant, you can't start from "everything" and subtract. A rule for * with read + write gives write everywhere — a second, narrower rule can't take that write back. Grant the specific paths you want instead.

Templates

When you create a role, you can start from a template and adjust it. Each template is just a starting set of rules — edit, add, or remove anything before saving.

Template	Grants
Viewer	Read-only across the whole project (* read)
Contributor	Read and write everywhere, no delete (* read + write)
Release	Full control of releases/, read access to documents/
Device	Read and update todos/ only — the shape a HAL device uses
Full Access	Read, write, and delete everything (* all actions)

Assigning roles to HAL devices

A HAL device is a first-class member of a project, just like a person — you assign it a role on the project's Members tab. A device only has the access its role grants; there is no owner shortcut for devices.

The common case is a device that works tasks: give it a role with read + write on todos/ (the Device template) and it can pull its assigned todos and report progress, without access to anything else in the project.

Managing todos through a role

Todos live in the todos/ folder, so a role's access to them follows the same rules as any other folder:

Permission on todos/	What it allows
Read	See and list todos
Write	Create todos; change status, title, assignee
Delete	Remove todos

A role with * covers todos too. See ToDos for the full task workflow.