Integrations

An admin-only card in Workspace settings connects Can to another app. Integrations mints a credential that app uses to call Can's API as itself — a member of your workspace, with a name, an audit trail, and a revoke button.

The card is visible only to workspace admins, and an integration is workspace-wide: one connection covers every board in the workspace.

Three kinds of credential

Can's REST API accepts three credentials, and which one you want depends on who is acting.

Credential Prefix Acts as Comes from
OAuth 2.0 access token — You, through a client you approved The OAuth flow, per session
Personal access token rft_can_ You API tokens in workspace settings
Workspace integration credential rfi_can_ The connection itself Integrations in workspace settings

The distinction that matters: a personal access token is you acting as you, so it carries your memberships everywhere you are a member and should never be handed to another app or another person. An integration credential is another app's workspace acting as itself — a member of exactly one workspace, and of nothing else.

The first two are covered in REST API and OAuth. The rest of this page is the third.

What an integration is

Connecting an app's workspace to yours creates a member in your workspace, not a hidden key. The member's id is integration:<app>:<origin workspace id> — say integration:acme:abc123 — and the credential Can mints names that member as its principal.

That has consequences worth knowing:

  • It appears in the member list, with the display name you gave it and an integration badge where a role would be. There is no role to pick: an integration is a plain member.
  • It is scoped to one workspace by construction. The principal exists in exactly one member list, so whatever else the connecting admin can see, the credential cannot reach it.
  • Any admin can revoke it, and it outlives the admin who installed it leaving or being demoted.
  • Every request is authorized live against that member doc, the same read that authorizes a human.

Connect an app

In Workspace settings → Integrations:

  1. Enter the app slug — lowercase letters and digits, naming the app on the other side. It becomes the middle segment of the member id. A few slugs (github, gitlab, bitbucket, linear, jira, slack) are reserved for connected services and are refused here.
  2. Paste the origin workspace id — the id of the workspace on the other side, from that app's settings.
  3. Give it a display name, up to 100 characters. It is what shows in the member list, so name the connection: Acme Support.
  4. Press Connect.

Can mints an rfi_can_… token and shows it exactly once. Copy it before you dismiss the banner; only a hash is stored, so a lost credential means revoking and connecting again. An origin workspace can be connected once — connecting the same one twice is refused until you revoke the first.

Minting requires being signed in to Can. An OAuth token, a personal access token, or an integration credential cannot create another integration.

Revoke

The trash button beside an integration deletes the member doc and every token minted for that principal. Access stops on the connected app's next request: verification is a live lookup, so there is no propagation delay.

Removing the integration from the member list disables the credential too, for the same reason — a principal with no member doc gets a 404 from every workspace endpoint. The Integrations card is the tidier gesture, because it also clears the token record.

Connected services

Below the credentials, Connected services lists services that send Can events, each connected through that service's own install flow. GitHub is the one service offered so far, with a Connect GitHub button beside the heading.

A connected service is a member too, integration:<service>:<install id>, so its changes are attributed in History like any integration's. The trash button disconnects it, and so does removing that member from the member list. Delivery log shows the last 50 events the service sent: when each arrived, what it was, and what Can did with it, or why it did nothing.

Each connection shows a status. active means Can acts on its events. suspended means the service paused the install on its side, and Can skips its events until it is resumed. disconnected means the install was removed on the service's side: nothing more arrives, and the row stays until an admin removes it with the trash button.

GitHub

Connecting GitHub installs the Can by Random Fact GitHub App on a GitHub account or organization. From then on, a pull request that names a ticket key gets linked to that ticket, and the link follows the pull request's state.

Install

  1. In Workspace settings → Integrations, press Connect GitHub. Only workspace admins see the button.
  2. GitHub shows the App's install page. Pick the account or organization, and either all repositories or the ones you choose. GitHub then asks you to authorize the App, so Can can confirm that your GitHub account can manage the installation you picked.
  3. GitHub sends you back to workspace settings, and the connection appears in the list under the account's name.

The link from Connect GitHub works once and for 30 minutes. One installation connects to one Can workspace; connecting it to a second is refused until it is disconnected from the first.

If you are a member of the organization but not an owner, GitHub sends the owners a request to approve the install instead, and nothing is connected yet.

Connect GitHub connects a new installation. To connect an account where the App is already installed, for example after disconnecting it in Can, uninstall the App from that account's GitHub settings first, then press Connect GitHub again.

What gets linked

Can reads each pull request's title, description and branch name for ticket keys, and links the pull request to each matching ticket in this workspace. It reads them again whenever the pull request is opened, edited, reopened, gets new commits, moves to or from draft, or is closed.

  • In the title and description a key must be in capitals, as CAN-123, so words like covid-19 are not read as keys. A key inside a URL counts.
  • In the branch name, case does not matter, so feat/can-123-retry links CAN-123.
  • Keys resolve only in the connected workspace. A key for a board that is not there is listed in the delivery log as not found.
  • Links only accumulate. Removing a key from a pull request leaves its link in place, though rules stop acting on it; delete the link on the ticket if it no longer applies.

A ticket's link shows the pull request's title and state, open, draft, merged or closed, and updates as the pull request changes. GitHub can deliver events out of order, so Can keeps whichever state GitHub stamped most recently. State updates reach every link to that pull request in the workspace, including links added by hand.

A new link records one History entry on the ticket, attributed to GitHub on behalf of the GitHub user who acted, such as GitHub on behalf of octocat. State changes are not recorded in History.

Permissions

The App asks for read access to pull requests, plus the read access to repository metadata that every GitHub App has. It cannot push code, comment, or change anything on GitHub. It receives pull request events, and events about its own installation.

Disconnect

The trash button removes the connection in Can, and Can stops acting on that installation's events. The App stays installed on GitHub until you uninstall it there.

Uninstalling the App on GitHub marks the connection disconnected; suspending it there marks it suspended, and Can skips its events until it is unsuspended. In either case, links already on tickets stay.

Rules

A connected service can act on tickets as well as link them. Its rules sit under it in Connected services, and each rule says what to do when the service reports a particular event. A GitHub connection starts with one: when a linked pull request merges, move the ticket to the first done column on its board.

Each rule has an Enabled box and three options:

  • Move the ticket to the first done column on its board (the leftmost, by board order), or a column you choose. A chosen column belongs to one board, so a rule that targets one applies only to that board.
  • Act once all linked PRs are merged or closed, or as soon as any linked PR merges. The first is the default, so a ticket split across two pull requests stays put until the second one is resolved, and at least one of them has to have merged. A PR link Can has never received an event for counts as unresolved. Web links are not pull requests and never hold a ticket back.
  • Boards: the boards the rule applies to. Every board starts checked, and while all of them are checked the rule also covers boards created later. At least one stays checked; to stop a rule, clear its Enabled box.

Changes save as you make them.

A rule acts on every ticket with a link to the pull request the event is about, whether the link was added by hand, through the API, or by the service itself. The move is an ordinary one: it shows in the ticket's History as the connection, on behalf of the account behind the event, and the ticket goes to the bottom of the column.

Which mentions close a ticket

A link the service added moves its ticket only when the pull request is for that ticket: the key is in its title or branch name, or follows a closing keyword in its description. The keywords are GitHub's: close, closes, closed, fix, fixes, fixed, resolve, resolves and resolved, in any case and with an optional colon, so Fixes CAN-12 and closes: CAN-12 both count. Each keyword closes one key: in Fixes CAN-12 and CAN-13, only CAN-12 closes.

Any other mention in the description, like see CAN-14 or follow-up: CAN-15, still links the pull request, but no rule moves that ticket for it, and the delivery log lists it as only mentioned in the PR description. A negated keyword, as in does not fix CAN-16, is a mention too. Such a pull request does not hold the ticket back under Act once all linked PRs are merged or closed either. Links added by hand or through the API always count.

Some things a rule never does:

  • It never moves a ticket out of a done or won't-do column. A ticket that is already finished stays where it is.
  • It never undoes what a person did. Rules run when an event arrives and at no other time, so if you drag a ticket back out of Done, it stays where you put it. Only a new event can move it again, and the same event delivered twice moves nothing the second time.
  • It does not trust a hand-added link whose address disagrees with the pull request it names. That ticket is skipped.

When a rule skips a ticket, the Delivery log says why: already done, board has no done column, waiting on other linked PRs, only mentioned in the PR description and so on. Moved tickets are listed there too.

Attribution

Requests from an integration can carry an x-on-behalf-of header: JSON holding a display name and the origin app's own person key, never an email, naming whoever triggered the action over there. Can records that claim on the ticket's activity entries, and the ticket's History tab reads the whole line as Acme Support on behalf of Maya: the integration's display name as the actor, then the claim. Activity entries also record a via value of integration:<display name>, which rides along in board exports; History leaves that one off, since the actor already carries the name.

Treat the claim as audit-grade, not authorization-grade: it is exactly as trustworthy as the integration you installed. Permissions come from the member doc; the header never grants anything.