Connect a plugin to another system
For: cluster and tenant administrators.
A connection is how a plugin's tools reach another system as your tenant: a GitHub App on your organization (ai.oz0/github), a workspace's bot. A plugin declares it; an admin of the tenant connects it once, in the browser; and from then on each call the connection covers gets a token minted for that call on the edge. Until a connection is connected, its calls get its fallback secret, if it has one, such as GITHUB_TOKEN.
Choose a task
| Task | Guide |
|---|---|
| Renew and reconnect credentials | Open guide |
| Restrict connection destinations | Open guide |
| Diagnose connection failures | Open guide |
| Understand connection security | Open guide |
Connect one
In the console, Credentials, Connections (admins only) lists every connection the tenant's plugins declare and what calls get now:
| Status | Calls get |
|---|---|
| connected | a token minted for each call, or the secret the connection saved |
| token | the fallback secret, such as GITHUB_TOKEN |
| at step ... | a flow is under way; the fallback secret meanwhile |
| failed | the fallback secret; the last step's error is on the connection |
| needs reconnecting | nothing: the provider refused to renew the token (in this guide) |
| not connected | nothing: the call is not made, and the agent reads how to connect |
Open a connection, fill in its params, and click Connect. The browser goes through the other system's pages, such as GitHub's to create and install an app, and comes back to the page. The same from the CLI:
oz0 connection list
oz0 connection start github --param owner=acme --open
oz0 connection show github
connection start prints a URL; open it within 15 minutes, once. It also lists the steps (on stderr, so the URL stays alone on stdout), and --wait 15m follows them and their checks until the connection is connected. --from-step install starts at a later step, such as installing an app that is registered already on another organization.
A param with choices picks which steps run: GitHub's account is organization (the default) or user, for a GitHub App on your own personal account, whose registration goes to another page of GitHub's. The console shows such a param as a select and lists only the steps it runs; connection show says which steps run for which value (when account=user). A step needs the params it reads, so a user's app needs no owner:
oz0 connection start github --param account=user --param app_name=ada-oz0 --open
A connected connection keeps working while you connect it again from its restart step (connection show names it; for GitHub, Slack and Discord, install): calls get the app's tokens until the new flow is done, and an abandoned or failed flow changes nothing.
Starting from an earlier step, such as registering a new GitHub App, replaces the connection at once, so it needs --replace (in the console, the Replace checkbox): calls get the fallback secret until the new flow is done.
connection set stores params without starting anything, such as an API's address for the fallback token; it works before the plugin is installed, so that the plugin's quality gate already uses it.
A fallback token set by hand goes to such an address only once it is bound to it (oz0 secret set GITHUB_TOKEN --host ghe.example.com; see where credentials go).
connection delete forgets the connection and the secrets its steps saved, even once its plugin is removed (its fallback secret stays, and an app it registered stays on the other system until you delete it there).
A step that saves over a tenant secret that was set before, such as a GITHUB_WEBHOOK_SECRET you set by hand for repository webhooks, says so on the Connections tab and in its audit entry.
A Slack or Discord connection made before its first step pasted the Client ID has the first step as its restart step: Connect again starts there, and you paste the existing app's credentials, so it keeps working meanwhile.
oz0 connection start --wait 15m follows the steps and exits with an error when one fails, also for a connection that stays in effect.
Your own app, about two minutes
Slack, Discord, Microsoft Teams and GitHub each send their events to one URL per app, and your events go to your own edge, so every cluster uses an app of its own: there is no shared app of the project's, and nothing of yours passes through anyone else's servers. Connect makes yours close to one click:
| Provider | What you do | What is checked before the next step |
|---|---|---|
| GitHub | Confirm on GitHub's page: the app's manifest has the webhook URL, the permissions and the events the plugin needs, and its name defaults to your tenant's plus -oz0. Then pick the repositories. | The edge reads the installation with the app's own key. |
| Slack | Create the app on Slack opens Slack with your app's manifest filled in (the /oz0 command, the events and interactivity, all pointing at your edge, and the bot's scopes). Paste the Client ID, Client Secret and Signing Secret on the edge's page, click Retry next to the Request URL on Slack's Event Subscriptions page, then allow the app in your workspace. | Slack's oauth.v2.access checks the Client ID and Client Secret when you paste them; Slack's signed URL check proves the signing secret and the URL; Slack's auth.test checks the bot token. |
| Microsoft Teams | About ten minutes: create an Azure Bot (single tenant) in the Azure portal and paste its app ID and tenant ID; paste a new client secret; copy the messaging endpoint into the bot, add its Teams channel, and upload the Teams app package the edge builds. | Your tenant's token endpoint grants the bot a token for the pasted secret before it is sealed; Teams' first activity, with a token the Bot Connector signed for this bot, proves the endpoint and the app ID. Each post then gets a token the edge mints with the client secret, which never leaves the edge. |
| Discord | Discord has no app manifest, so the edge's page guides you: open the developer portal, make an application, paste its Application ID, Public Key, Client Secret and bot token, paste the Interactions Endpoint URL and the Redirect the page shows into the portal, then pick the server. | Before anything is saved, GET /users/@me checks that the token is a bot's, GET /applications/@me that it is this application's, and a client credentials grant that the Client Secret is; Discord's signed PING proves the public key and the URL. |
These steps run on the edge's own page: the console's Connect (or Go on at ... for a flow under way) and oz0 connection start open it. What you paste there goes to the edge alone, which seals each secret as a tenant secret (SLACK_SIGNING_SECRET, DISCORD_BOT_TOKEN, ...) and never shows it again; the Connections tab and connection show show each step, each check's result and when it ran, never what was pasted.
A field in the wrong box (a bot token where the signing secret goes) is caught before anything is saved or sent, and a check that fails says why at its own step; paste again on the same page. While a step waits for Slack's or Discord's signed request, the page looks again every three seconds and goes on by itself.
For any of them, the edge's HTTPS port must be reachable from the provider and your browser at --public-edge-url, with a certificate they trust (in this guide). A cluster without a public edge cannot use these apps yet: receiving events over an outbound connection instead is being evaluated.
After connecting
A connection may run functions of its plugin once its last step is done, such as checking which repositories a GitHub App was installed on, or registering a bot's commands. Each runs as a tool job of its own, as oz0 tool call starts one: on an online node that has the function ready, through that node's tool policy, hooks and approvals, with the new token like any covered call.
The page does not wait for them; the Connections tab and connection show list each run with its job (oz0 job get <job>), or why it did not start (no node had the plugin ready, for example), and the audit trail has a connection.after entry for each. Connecting again runs them again.
After connecting: oz0_github.check_installation
Ran after: oz0_github.check_installation as job tool-6b1f... on node n1, 4s ago (oz0 job get tool-6b1f...)
Previous section links
Tokens that renew themselves: open guide.
Reconnecting: open guide.
Where credentials go: open guide.
A host of your own: open guide.
Troubleshooting: open guide.
Where everything goes: open guide.
Tokens bound to the node: open guide.
What the edge needs: open guide.