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.
Limits
Section titled “Limits”| 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.
Members and maintainers
Section titled “Members and maintainers”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.
Notifying subgroups
Section titled “Notifying subgroups”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.
Keys, agents and channels
Section titled “Keys, agents and channels”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:manageor by maintaining the group, and only for actions you hold yourself and the group holds there. Its operation scope is one ofdeployments:read,deployments:write(the default),logs:read,ci:write,registry:write,registry:read,images:readorimages: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 byhost.group_keys.
Who can do what
Section titled “Who can do what”| 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.
In the app
Section titled “In the app”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.
From the CLI
Section titled “From the CLI”canopy groups treecanopy groups create Payments --parent engineeringcanopy groups add payments ada@example.com --maintainerSee the CLI reference for every canopy groups command.
From the API
Section titled “From the API”GET /teams/{team_id}/groups?tree=true&q=POST /teams/{team_id}/groupsGET /teams/{team_id}/me/groupsGET /groups/{group_id}PATCH /groups/{group_id}POST /groups/{group_id}/moveDELETE /groups/{group_id}GET /groups/{group_id}/membersGET /groups/{group_id}/keysPOST /groups/{group_id}/keysDELETE /groups/{group_id}/keys/{key_id}GET /groups/{group_id}/channelsPOST /groups/{group_id}/channelsDELETE /groups/{group_id}/channels/{channel_id}PUT /teams/{team_id}/agents/{agent_id}/owner-groupPUT /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.