Skip to content

Groups

A group is a named set of an Organization’s members, for example Engineering, and Payments inside it. Groups nest: a group has at most one parent, and a member of Payments is also, for lists and filters, a member of Engineering. A group holds no resources and changes nothing anyone can do by itself. What a person may do is decided by their role in the Organization, plus any access given to the groups they are in; groups name who works together so that a System can have a team as its owner and watcher, and its build and deploy notifications reach that team instead of everyone.

Limit Value
Depth of the tree 5 levels
Groups in an Organization 500
Members in a group 1000

A group’s name is at most 100 characters. Its slug is made from the name and is unique in the Organization. A group can have a description and a contact (a channel or an address), both optional.

Every member of a group has a role in it:

  • Member: listed in the group.
  • Maintainer: manages the group’s members. A maintainer of a group, or of any group above it, can add and remove its members and change their roles, without any role in the Organization beyond being a member.

Only people who are already members of the Organization can be added. When a person leaves the Organization they leave all of its groups. Members that a directory (SSO or SCIM) manages are shown with their source and cannot be changed by hand.

By default a group stands for its direct members when it owns or watches a System. Turn on Notify members of subgroups in the group’s settings, or send notify_descendants, and it stands for the members of every group below it too. A person leaving the Organization, or a group being deleted, removes it from every System it owned or watched.

A group can own credentials and alerts, so they belong to a team instead of a person.

  • Keys. A group key is an API key made for the group. It is always tied to one place (the Organization, a project or an environment), lists the actions it may take there, and ends on a date (at most a year ahead). On every request it may do only what its own grant allows and what the group’s access gives at that moment, so removing or lowering a binding narrows the key at once. It never does more than the group, and it never turns into a personal key: if group access or group keys are switched off, or the group is deleted, it is refused. It keeps working when its creator leaves, because it is handed to another maintainer of the group (or the Organization’s owner). You make one with group:manage or by maintaining the group, and only for actions you hold yourself and the group holds there. Its operation scope is one of deployments:read, deployments:write (the default), logs:read, ci:write, registry:write, registry:read, images:read or images:write. A group key cannot open a shell in an environment.
  • Agents. An agent identity can name a group. The group appears on the agent and in the audit log, and gives the agent no access: its own permission list stays its whole authority.
  • Channels. A channel is a webhook that belongs to the group. It receives, signed, only the events of environments that the group owns or watches through a System (and, when an owning group notifies its subgroups, their channels too), from the moment it is created. Channels are switched off as a whole by the platform feature host.group_channels, and group keys by host.group_keys.
Action Needs
See the groups, their members and your own groups Any member of the Organization
Create, rename, move and delete groups group:manage, which the built-in admin and owner tiers have; a custom role can include it
Add, remove and change members of a group group:manage, or maintaining that group or a group above it

A group that still has subgroups cannot be deleted; move or delete the subgroups first. Moving a group moves its subgroups with it, and refuses a move that would make a group its own ancestor or push the tree past 5 levels.

Settings → Organization → Groups shows the tree with a search box. Open a group to see its path, subgroups, contact and members, and, if you can manage it, to add members, make someone a maintainer, remove a member or create a subgroup. Keys and Channels on the same page list what the group owns and, for the people who manage it, create and remove them. Access shows what the group’s members can do beyond their Organization role.

Terminal window
canopy groups tree
canopy groups create Payments --parent engineering
canopy groups add payments ada@example.com --maintainer

See the CLI reference for every canopy groups command.

GET /teams/{team_id}/groups?tree=true&q=
POST /teams/{team_id}/groups
GET /teams/{team_id}/me/groups
GET /groups/{group_id}
PATCH /groups/{group_id}
POST /groups/{group_id}/move
DELETE /groups/{group_id}
GET /groups/{group_id}/members
GET /groups/{group_id}/keys
POST /groups/{group_id}/keys
DELETE /groups/{group_id}/keys/{key_id}
GET /groups/{group_id}/channels
POST /groups/{group_id}/channels
DELETE /groups/{group_id}/channels/{channel_id}
PUT /teams/{team_id}/agents/{agent_id}/owner-group
PUT /groups/{group_id}/members/{user_id}
DELETE /groups/{group_id}/members/{user_id}

GET /teams/{team_id}/groups lists the groups with their level and member counts, or nested with tree=true, and filters by name or slug with q. GET /teams/{team_id}/me/groups returns the groups the caller is in (direct, with their role) and the ones above them (inherited). PUT .../members/{user_id} takes { "member_role": "member" | "maintainer" } and adds the member or changes the role. POST .../move takes { "parent_group_id": "<id>" | null }.

Creating, renaming, moving and deleting a group, and adding, removing and changing members, are recorded in the Organization’s audit log as group.created, group.updated, group.moved, group.deleted, group_member.added, group_member.role_changed and group_member.removed; keys and channels as group_key.created, group_key.revoked, group_channel.created and group_channel.removed; attaching an agent as agent.owner_group_set. A scoped API key can change groups only if its grant includes group:manage; otherwise it is refused with 403. If groups are switched off for your account the routes answer 403 with feature_disabled.