Systems
A System is a named group of environments of one Organization that run together, for example the API, the web app and the worker of one product, across several projects. A System holds no resources of its own: it points at environments, rolls up their health and lists their recent changes. Removing an environment from a System, or deleting the System, never touches the environment. An environment can belong to several Systems.
Health: serving and delivery
Section titled “Health: serving and delivery”A System answers two questions, because a failed build does not always mean a System that is down.
- Serving is whether the System is answering requests. It is the worst answer among the System’s production environments. While no environment is marked production, every environment counts, and the page says so.
- Delivery is what became of the newest build in each environment: delivered, in progress, failed or unknown. It reads every environment, so a failed staging deploy shows as a failed delivery without making the System look down.
An environment whose newest build failed before it was deployed, while an earlier build is still the one running, is
serving and its delivery failed (reason code delivery_failed_previous_serving). A failing health check or an open
finding counts against serving. A System without environments is unknown on both. The earlier single health stays,
as the worst of every environment.
An environment has a role in each System it belongs to: production, staging, development or preview. With
none set, Canopy reads one from the environment’s name (prod, production, live, staging, stage, stg,
preprod, uat, qa, dev, develop, development, test, local, preview, pr), as whole words, and
failing that from its branch (main, master, trunk, release, production for production; staging;
develop, dev). A derived role is marked as derived. Someone with system:manage can set a role from the
Environments list or with canopy systems role, and clear it to go back to the derived one. The same environment can
have different roles in different Systems. Changing a role is recorded in the audit log.
Timeline
Section titled “Timeline”The System page lists what changed across its environments in the last 14 days, newest first: who did it (the person the event names, otherwise whoever triggered the build, and then no one), the environment and its role, and the groups that own it through the System, the environment or its project, with their contact. Hand off on a change copies a message with the change, who did it, who owns it, the evidence it concerns and a link that opens the System page on that change. See Lists and Live Updates for the other fields.
Suggested Systems
Section titled “Suggested Systems”Open Systems and Canopy lists the groupings it found, each with the reason. Nothing is created until you keep one.
Canopy looks at recorded facts only and never guesses with a model:
- environments of the same project;
- environments built from the same repository and first directory. In a monorepo
host/apiandhost/appsharehost,cortex/apisharescortex. When every environment sits at the repository root the match is weaker and is marked a possible match; - a service on its own, in a repository of its own, that calls exactly one grouping (a service in a repository that other environments share has a directory of its own, so it is treated as its own product and a call does not make it a member): one of its variables, not marked secret, has a name that
ends in
URL,HOST,DOMAIN,ENDPOINT,ORIGINorBASE, and its value names a domain another environment of the Organization serves. Canopy reads those values on the server to match domains and shows only the variable’s name and the matched domain. A secret variable is never read.
A service that several groupings call, such as a shared login service, is listed as also used by other groupings on each of them and is not made a member of any, and one grouping calling another never merges the two. A single environment is never suggested on its own.
Each suggestion has a confidence: strong match when two kinds of evidence agree or the directory tells products apart, possible match for one kind, and weak match, check it for a grouping of more than 25 environments. It also lists the people who deployed or changed its environments most in the last 30 days, with the counts, when there are enough to say. Nobody is added as an owner by this.
Keep as a System creates the System with those environments and the suggested name; rename it afterwards in its settings. Dismiss hides the grouping for everyone in the Organization until its members change. Groupings that one System already holds in full are not shown again, and one that a System holds in part says so.
Suggestions need the system:manage action and the platform feature host.systems.discovery, which is generally
available and on by default; with it off the Systems list works as before and shows no suggestions.
Owners, watchers and who is told
Section titled “Owners, watchers and who is told”A System can have owners, the people or groups who answer for it, and watchers, who want to hear about it without answering for it. Either can be a person or a group, and a System can have up to 50 of each. A System also has a contact, a channel or an address; when you leave it empty, the contact of the first owning group that has one is shown instead.
Owning or watching a System grants no access to it. What a person may do is still decided by their role in the Organization, so an owner who is a viewer still cannot change the System. You can give the owning groups a role on the System’s environments or projects in one step; see Access.
A group stands for its direct members. If the group has notify subgroups turned on (in the group’s settings), it also stands for the members of every group below it. A group that reaches nobody is marked so, because nobody would hear about the System through it.
Build and deploy notifications (a build that failed, a deploy that went live, a deployment that failed for good) used to
go to every member of the Organization. For an environment that belongs to a System with owners or watchers, they now go
to those people only, joined across every System that holds the environment. They still go to every member of the
Organization when the environment is in no System, when its Systems have no owners or watchers, or when none of them is
a current member. Nobody is left unnotified. The platform feature host.systems.routing decides this; it is generally
available and on by default, and with it off every member is notified as before while the owners and watchers are kept.
Watch yourself from the System page, or with canopy systems watch. Anyone who can read a System can watch it;
changing the owners, the contact, or who else watches needs system:manage. Adding or removing an owner or a watcher is
recorded in the audit log, and a person who leaves the Organization stops owning and watching.
Security notifications (a production exposure that has a fix, a failed verification, a fix that reached production) go to the owners and watchers the same way; see Security findings.
Relations and delivery
Section titled “Relations and delivery”Relations say what a System depends on and what depends on it: GET /systems/{system_id}/relations. A relation is
inferred, never stored: a plain (non-secret) variable of one System’s environment, whatever its name, points at a domain
of another’s, or a service’s runtime egress list names it (evidence.kind is variable or egress). Each relation names
the other System with its state, its owners and its contact, and the evidence (the variable’s name and the host, never the
value). used_by lists the Systems that may be affected if this one fails. unassigned lists related
environments that belong to no System, and drift says what looks out of place: a related environment with no System, or
environments of a member’s project that are in no System. The scan covers up to 200 environments and 5,000 variables
(truncated says when it hit them) and is kept for five minutes. Systems and environments you cannot read are left out.
A drift note has a key; POST /systems/{system_id}/drift/{key}/dismiss (canopy systems drift <system> dismiss <key>,
needs system:manage, audited) hides it until the set of environments it is about changes, and
DELETE /systems/{system_id}/drift/{key} shows it again. dismissed_drift counts the hidden ones.
Delivery (GET /systems/{system_id}/delivery) gives each environment you can read its newest build (status, number,
commit, the failure stage and kind, times) and what is live.
The staging gate. With staging_gate set to hold (PATCH /systems/{system_id}, canopy systems gate <system> hold),
a deploy of a production environment of the System waits for approval, through the existing approval flow, while a staging
environment of the same System, built from the same project or repository, has failed to build that commit. The build log
says why, held_by on the System’s delivery and on GET /teams/{team_id}/approvals names the failed staging build, and an
approver can still let it through. A staging build that is still running, or none, holds nothing; a staging retry that
succeeds lifts the hold; an emergency deploy is never held. The default is off.
Push impact (GET /teams/{team_id}/push-impact?repository=&branch=) says what a push would rebuild: the environments
that track that branch of that repository (owner/name or its URL), their Systems with owners and contact, the other
Systems that may also be affected, and the production environments that would wait for staging. Failure notifications of an
environment other Systems depend on end with “May also affect: …” and name only the Systems each person may read, and
the owners and watchers of the Systems that use it get their own notification (“A System that X depends on had a
failure”), once, naming only what they may read, while host.systems.routing is on. Each environment of GET /teams/{team_id}/systems and GET /systems/{system_id} also carries its newest build.
From the CLI
Section titled “From the CLI”canopy systems suggestionscanopy systems keep <fingerprint> --name "Host platform"canopy systems dismiss <fingerprint>
canopy systems owners add checkout --group paymentscanopy systems owners add checkout ada@example.comcanopy systems owners list checkoutcanopy systems watch checkoutcanopy systems minecanopy systems contact checkout "#checkout"
canopy systems timeline checkout --days 3canopy systems role checkout checkout-staging stagingcanopy systems role checkout checkout-staging --clear
canopy systems relations checkoutcanopy systems delivery checkoutcanopy systems push-impact --repository acme/checkout --branch maincanopy systems gate checkout holdcanopy systems drift checkout dismiss <key>A System is its id, slug or name. watchers add|remove|list work like owners, and owners remove and watchers remove take the same user or --group. timeline prints times in your local time; --days goes back at most 14. relations, delivery, push-impact, gate and drift are described under Relations and delivery.
GET /teams/{team_id}/systems/suggestionsPOST /teams/{team_id}/systems/suggestions/{fingerprint}/dismissPOST /teams/{team_id}/systems
GET /systems/{system_id}/ownersPUT|DELETE /systems/{system_id}/owners/users/{user_id}PUT|DELETE /systems/{system_id}/owners/groups/{group_id}GET /systems/{system_id}/watchersPUT|DELETE /systems/{system_id}/watchers/users/{user_id}PUT|DELETE /systems/{system_id}/watchers/groups/{group_id}GET /teams/{team_id}/me/systems
GET /systems/{system_id}/timelinePUT /systems/{system_id}/environments/{environment_id}/roleGET returns suggestions[] with fingerprint, name, confidence, environments[], signals[], references[]
(from, to, variable, domain), shared_dependencies[], suggested_owners[] and overlaps[], and
truncated / references_partial when a large Organization was read in part. It is computed on every request and not
stored.
POST /teams/{team_id}/systems also takes environment_ids (up to 200 environments of the Organization) and
suggestion_fingerprint. The System and its members are created together; an environment of another Organization
makes the whole request a 404 and creates nothing. With a fingerprint the members are marked as suggested and the
grouping is recorded as kept.
GET .../owners returns owners[] with kind (user or group), name, people (how many current members the owner
reaches) and, for a group, slug, contact and notify_descendants, plus contact and contact_source (system,
owner_group or null). GET .../watchers returns watchers[] and viewer_watching. The PUT calls are idempotent: 201
when added, 200 when already there. PATCH /systems/{system_id} also takes contact. GET /teams/{team_id}/me/systems
lists the Systems you own or watch, directly or through a group.
GET /systems/{system_id} and each System of GET /teams/{team_id}/systems carry serving (state, basis of
production_members, all_members or none, reason, environments[], unknown_environments[]) and delivery
(state of succeeded, in_progress, failed or unknown, reason, failed_environments[],
in_progress_environments[], unknown_environments[]); each environment carries role, role_source (set or
derived), serving, delivery and delivery_reason. GET .../timeline takes days (1 to 14), limit (1 to 200)
and cursor and returns items[] (actor with source of event or build, environment with its role,
owner_groups[], refs[]), next_cursor and the window. PUT .../environments/{environment_id}/role takes
{"role": "production" | "staging" | "development" | "preview" | null}; null clears it.
Creating, renaming, deleting a System, changing its members and their roles, owners and watchers, and dismissing a suggestion are recorded in the audit log. API keys limited to one project or environment cannot read or change Systems.