Custom roles

Every workspace has three built-in roles: member, admin and owner (Workspaces and roles). A custom role is one you name, with exactly the permissions you pick. Give it to a member directly, or to a group, so everyone in the group holds it.

Custom roles are an Enterprise feature. They’re included on Business for early customers, for a limited time.

Permissions

Permission	What it lets someone do
apps.deploy	Make apps and change them: deploy, roll back, previews, env vars, secrets, schedules and bypass tokens. They still need to be an editor or owner of an app to change it.
apps.share	Change who can open the apps they own, change their visibility, add and remove their custom domains, and delete them or restore them from the bin.
members.manage	Add members and remove them, and give them a custom role, but not to someone who can already do more than they can.
groups.manage	Make groups and choose who is in them, but not their own place in one. Adding someone to a group shared with apps shares those apps, so they need to be able to share each of them too.
audit.view	Read the whole audit log and the Activity tab.
billing.view	See usage and billing, and open an Enterprise contract’s invoices. Like anyone with an invoice’s link, they could pay it from there. The card, the usage limit and the plan stay with the owners.

A member with no custom role has apps.deploy and apps.share, as every member always has. A member with one or more custom roles has exactly what those roles name, and nothing else. So a role can take something away as well as add it: a member whose only role is audit.view can read the log but can’t deploy.

Owners and admins always have every permission. A custom role is for members only. Making someone an admin or an owner takes their custom role away.

Nothing here changes who can open an app. The app’s sharing decides that, checked at the edge on every request.

Make a role

Owners and admins make roles:

jiayang role create acme auditor --permissions audit.view,billing.view --description "Reads the log and the bill"

Made the auditor role in acme. Give it with `jiayang role assign acme auditor <email>`.

A name is up to 30 lower-case letters, digits and single dashes, and can’t be owner, admin or member. A workspace has up to 50 roles.

A role can name no permission at all, with --permissions none. Its holders can only open what’s shared with them: they can’t make apps, share them or see the log.

jiayang role list acme shows each role, what it lets its holders do, who holds it and which groups give it. Every member can see the list.

To change what a role lets its holders do, list all of it again:

jiayang role update acme auditor --permissions audit.view

The change applies on each holder’s next request.

Give a role

jiayang role assign acme auditor dana@example.com

dana@example.com has the auditor role in acme.

Or when you add them:

jiayang workspace add acme dana@example.com --custom-role auditor

jiayang workspace members acme shows each member’s custom roles beside them, the ones a group gives too:

member  dana@example.com (auditor)
member  sam@example.com (auditor, through it-auditors)

To take a role given directly away:

jiayang role unassign acme dana@example.com

In the dashboard, the Members page has a Custom role column and a Roles section.

Give a role to a group

A group can give a role to every member of the workspace in it:

jiayang role assign acme auditor --group it-auditors

The it-auditors group gives the auditor role to the members of acme in it.

Someone in the group who isn’t a member of the workspace gets nothing from it. Someone in two groups, or with a role of their own too, has everything all their roles name.

When your identity provider fills the group over SCIM, the provider decides who holds the role. Take someone out of the group there, and the role is gone from their next request.

jiayang role unassign acme --group it-auditors stops the group giving it.

Who can give what

• Owners and admins make, change and delete roles, and say which group gives which.
• Anyone with members.manage can give members a role, or take it away, and add or remove members. They can only give a role whose permissions they all have themselves. They can’t change their own role, and can’t add, change or remove an owner or an admin, or a member who can do something they can’t, through a role or a group.
• Anyone with groups.manage can make and fill groups, except a group that gives a role. Otherwise they could give themselves the role by joining it. They can’t add themselves to a group or take themselves out. A group opens every app shared with it, so adding someone to a group that’s shared with apps shares those apps. They can only do that if they could share each of the apps themselves: they have apps.share and own the app. Taking someone out of a group always works, since it only takes access away. Deleting a group shared with apps unshares them, so that needs the same: they could share each of the apps themselves.

Someone who tries to give more than they have sees:

error: You can only give someone what you can do yourself, and the auditor role lets them do more.

The database draws the same lines under the API, so a request that got past the API would still be refused.

Delete a role

jiayang role delete acme auditor

A role someone holds, or a group gives, can’t be deleted. Give them another role first. That way nobody gets a member’s permissions back because their role went away.

On a plan without custom roles

If your workspace moves to a plan without them, roles already given keep taking away what they took away, and stop adding anything. A member whose role was audit.view alone can’t deploy, and can’t read the log either. You can still take roles away, narrow one or delete one. Making, widening or giving one is refused, and the refusal goes in the audit log as plan.limit with roles.

In the audit log

role.create, role.update and role.delete record each change to a role. member.role records someone given a role or having it taken away, and group.role a group starting or stopping giving one.