Choose and create roles for your team

A role is a named set of permissions. Every member of an organisation has exactly one role, and the role answers "what may this person do?". SrvYard ships five built-in roles for the common jobs, and on plans that include teams and roles you can create your own for the rest.

This article explains what the built-in roles allow, how the permission list is organised, and how to clone a built-in role or build a custom one. A role says what a member can do; which servers and sites they can do it on is decided separately by teams: see Limit members to certain servers and sites.

Before you begin#

• Permission to view roles. Anyone with roles:view can open the page. Creating, editing and deleting custom roles needs roles:manage, which owners and admins have.
• A plan with teams and roles. The built-in roles work on every plan. Creating custom roles is part of the same plan feature as teams, which the Business plan includes. See Plans and limits compared.
• A permission you hold yourself. You can only give a role permissions that you have. If you try to grant one you do not hold, SrvYard refuses and names it.

1. Read the Roles page#

Open Settings in the sidebar and choose Roles. The description says: "A role is a set of permissions. Give each member the role that fits what they do; teams then decide which servers and sites they see."

1. New role. Starts a custom role from scratch (step 3).
2. Built in. A badge on the five roles that come with SrvYard. They cannot be edited or deleted. The Members column counts the people who have the role (and pending invitations for it), and Permissions says how many of the 102 permissions the role holds.
3. Custom. A role you created, here Release manager, with its description.
4. Permissions. The count for that role, such as "5 of 102". Each row also has a three-dot menu at its right-hand end, described in step 4. (On this screenshot the menu button sits just outside the picture because the table is wider than the window.)

2. What the built-in roles allow#

The one-line descriptions leave out some details that matter:

• Admin cannot delete the organisation, manage billing, sign in as another member (impersonate) or export secrets. These stay with the owner.
• Manager also cannot manage the organisation's integrations, storage providers, organisation-wide SSH keys or webhooks, run migrations, or use export and import. They can invite and manage members and teams.
• Developer works on servers and sites but cannot create, delete, archive, transfer or reboot servers, view server credentials, manage members, teams or notification channels, or see webhooks. They can deploy, edit environment variables, manage daemons and scheduled jobs, run recipes and use the web terminal.
• Viewer can see everything, including sensitive data, but cannot change anything. A viewer who is in no team still sees every server and site, because the Viewer role holds the permission that allows it (see below).

3. Create a custom role#

Press New role. A panel opens with the title New role and the line "Choose what members with this role are allowed to do."

1. Name. Up to 60 characters. It must be unique in the organisation and cannot be the name of a built-in role.
2. Description. Optional, up to 255 characters. It shows in the roles table and in the role menus when you invite or change a member, so write what the role is for.
3. Search permissions. Filters the long list by key or description.
4. Select all. The box next to a group's name ticks or clears every permission in that group. Each group also shows how many of its permissions are ticked, for example "0 of 3". The counter at the top right of the list shows the total.

Tick at least one permission, then press Create role. The role is available straight away in the invitation panel and in each member's role menu.

How the permissions are named#

Permissions are written as area:action, and the groups follow the areas of the product: Organization, Members, Roles, Teams, API, Billing, Integrations, Server providers, Source control, Storage providers, SSH keys, Recipes, Resources, Servers, Sites, Backups, File backups, Snapshots, Monitoring, Notifications, Webhooks, Dashboards, Import / migrate, Export / import and Activity.

1. sites:view. See sites, deployments and environment files. Almost every role needs it, because most other site permissions only make sense once the person can open the site.
2. sites:manage-deploys. Deploy the site, roll back and update the deployment script. Together with sites:view and servers:view this is the whole of the Release manager example: a person who can see everything and ship releases, but not touch servers.

Two permissions deserve a closer look:

• resources:access-all lets a member see every server and site even when they are in no team. Without it, a member sees only the servers and sites their teams share, plus the ones they created.
• servers:view-credentials lets a member view and download the sudo and database administrator passwords of servers. Hand it out sparingly.

4. Clone a built-in role#

The quickest way to a good custom role is to start from the nearest built-in one. Open the three-dot menu of the role.

1. View permissions. For a built-in role this opens the permissions in read-only form, with the note "Built-in roles cannot be changed. Clone one to start from its permissions." On a custom role the same place says Edit and opens the editor.
2. Clone. Opens a panel titled with Clone and the role's name, with its permissions already ticked.

1. Name. The panel suggests the old name followed by "copy", for example "Developer copy". Give it a name that says what the role is for.
2. Search permissions. Untick what the new role should not do, tick what it needs, and press Create role.

For a custom role, Delete asks for confirmation. If members or pending invitations still use the role, the dialog asks you to choose the role they move to first, so nobody is left without one.

5. Give someone the role#

Choose the role in the invitation panel, or change it later from the Role column of the Members page. Changes take effect on the person's very next request: you do not have to ask them to sign in again. See Invite team members and manage who has access.

Troubleshooting#

• "You cannot grant permissions you do not have yourself." Ask an owner or admin to create the role, or choose only permissions that you hold.
• "That name belongs to a built-in role." Choose a different name. Names are compared without regard to capital letters.
• The New role button is missing, or creating a role is refused. Your plan does not include custom roles, or your own role lacks roles:manage.
• A member can open a page but every button is missing. The role has the view permission but not the manage permission for that area. Check the group in the role editor.
• A member sees no servers at all. Their role does not include resources:access-all and they are in no team that shares a server. Add them to a team.
• I deleted a role and the members changed role. That is by design: you choose the role they move to in the delete dialog.

Related#

• Invite team members and manage who has access: hand out the role.
• Limit members to certain servers and sites: combine roles with teams.
• Least privilege and auditing: a way of thinking about which role to pick.
• Plans and limits compared: which plan includes teams and custom roles.