Integrations and Plugins¶

A plugin is a Python package that connects Imbi to an external platform, for example GitHub or PagerDuty. An integration is one configured instance of a plugin in an organization. It holds the connection options, the encrypted credentials, and the capabilities that you turn on.

One plugin can have many integrations. For example, one organization can have a github integration for github.com and a second github integration for a GitHub Enterprise Server appliance.

The Admin menu shows only for platform administrators.

For the pages of each plugin, see Plugins. To write a plugin, see Authoring Plugins.

Capabilities¶

A plugin declares one or more capabilities. Each capability is one kind of work that Imbi can ask the plugin to do.

A capability is either project-scoped or organization-wide. An organization-wide capability, for example identity, applies to the full integration. A project-scoped capability applies to projects, as Assignments describes.

Plugins¶

Plugins are installed with the server. You cannot install or remove a plugin from the UI. The Imbi distribution includes these plugins: aws, github, google, logzio, oidc, pagerduty, and sonarqube.

A plugin that Imbi finds for the first time is disabled. Enable it before you make an integration of it.

1. Open Admin > Global Admin > Plugins.
2. Find the plugin in the list. The list shows its capabilities, its package version, and the number of integrations in the selected organization.
3. Turn on the Enabled switch.

The setting is in the database. It stays the same after a restart.

When you disable a plugin, Imbi keeps all integrations of the plugin and their configuration. Imbi does not resolve the capabilities of these integrations, and the integration pages show plugin unavailable. The integrations are read-only until you enable the plugin again.

To stop Imbi from loading a plugin at all, add its slug to the IMBI_PLUGINS_DISABLED setting. To load a plugin package that does not use the imbi_plugin_* module name, add its import path to IMBI_PLUGINS.

Integrations¶

Add an integration¶

1. Select the organization in the top bar.
2. Open Admin > Organization Admin > Integrations.
3. Click New integration.
4. Plugin: select the plugin. The list shows only enabled plugins.
5. Connection: enter these values:
   • Name (required). Imbi makes the slug from the name.
   • Slug (required). Lowercase letters, digits, and hyphens. It must start with a letter. You cannot change it later.
   • Options. The plugin declares these fields. The plugin page lists each option.
   • Credentials. Required credentials show first. Click Show optional credentials to see the others.
6. Capabilities: turn on each capability that the integration must do. Each capability has its default state from the plugin. For a project-scoped capability, you can select project types. See Assignments.
7. Review: examine the values. Click Create integration.

Options and credentials¶

Options are not secret. Imbi stores them on the integration and shows them on the integration page. A capability can also have its own options. You set these under the capability toggle.

Credentials are secret. Imbi encrypts each credential with IMBI_AUTH_ENCRYPTION_KEY before it stores it. Imbi removes spaces at the start and the end of each value, and does not store an empty value. The UI never shows a secret credential again after you save it. A credential that the plugin marks as not secret, for example a GitHub App ID or an OAuth client ID, shows on the integration page.

Edit an integration¶

Open the integration from the list. The integration page has these sections:

• Connection: click an option or a credential to change it. Each change saves immediately. A credential row shows only whether a value is set.
• Capabilities: turn capabilities on or off, change capability options, and change the project types. For an identity capability that uses OAuth, the row shows the Callback URL to register with the provider. For a webhook-actions capability, the row shows the Delivery URL of each webhook of the integration. To make a webhook, see Webhooks.
• Danger zone: disable, enable, or delete the integration.

Click the name to change it.

Disable sets the integration status to inactive. Imbi keeps the configuration, but it stops all capabilities of the integration: Imbi does not bind the integration to projects, does not call its capabilities, and does not use it as a login provider or an identity source. Enable sets the status back to active.

Delete removes the integration, its credentials, its assignments, the EXISTS_IN links of projects to it, and the identity connections of all users to it. You cannot undo a delete.

Assignments¶

A project-scoped capability that is on applies to projects by these rules:

1. No project types selected. The capability applies to all projects in the organization.
2. Project types selected. The capability applies only to projects of those types.
3. Project override. A project can add its own assignment on its settings tab, in the Integrations card with Add Override. The override can change the capability options for that project.

Capability options merge in this order: the integration value, then the project type assignment, then the project override. The last value wins.

When two or more integrations give the same capability to one project, mark one assignment as the default. If no assignment is the default, a request for that capability fails with 400.

Each assignment can also hold per-environment payloads (env_payloads). The GitHub deployment capability sends them as workflow inputs. The payloads are one JSON object. Each key is an environment slug, and each value is a JSON object:

{
  "production": { "region": "us-east-1" },
  "staging": { "region": "us-west-2" }
}

To edit the payloads:

• Project type assignment. On the integration page, expand the capability. Under Environment payloads, edit the field of the project type. Imbi saves the value when the field loses focus. A capability that applies to all project types has no assignment, so it has no payloads.
• Project override. On the project settings tab, in the Integrations card, expand the override. Edit Environment payloads, then click Save Changes.

A project override payload merges into the project type payload for the same environment. The override value wins for each key.

The UI does not save a value that is not valid. It shows an error below the field.

You can also use the API: PUT /organizations/{org_slug}/integrations/{slug}/capabilities/{kind}/assignments. This PUT replaces all assignments of the capability, so send every assignment that you want to keep. When you change the project types on the integration page, the UI keeps the default, options, payloads, and identity integration of each assignment that stays.

Project links to integrations¶

A project can exist in an integration. Imbi stores this as an EXISTS_IN edge from the project to the integration. The edge holds:

Imbi uses the identifier to route webhooks. imbi-gateway finds the project of a delivery by its identifier and the integration slug. If no project has that identifier, imbi-gateway drops the delivery.

There are two ways to make the edge:

• The plugin writes it. A lifecycle capability writes the edge when it creates a remote resource. A Doctor fix writes it when it repairs the link. The plugin also records the identifier as verified.
• You write it. Open the project settings tab. In the Integrations card that lists the integrations the project exists in, click Add. Enter the integration, the identifier, and the URLs. This needs project:write.

An identifier that you add or edit by hand is not verified. Some features use only verified identifiers. For example, the github_app secret provider issues GitHub tokens only for a verified repository ID. To verify an identifier, use the Doctor fix of the plugin. See GitHub.

Identity connections¶

An identity capability lets each user connect their own account on the remote platform. Users connect at Settings > Connections. Imbi then calls the remote platform with the token of the user.

For an OAuth identity, register this redirect URL with the provider:

<IMBI_API_URL>/me/identities/<integration id>/callback

The integration page shows the full URL in the Callback URL field of the identity capability. The AWS plugin uses a device code and needs no redirect URL.

Act as service¶

A capability call normally uses the identity connection of the user. A service account has no identity connection. For the deployment capability, a service account can use the credential of the integration (a token or GitHub App credentials) instead. The service account must have all of these:

1. The permission of the endpoint, for example project:deployment:write, in its role in the organization that owns the project.
2. integration:act-as-service.
3. Membership in the organization that owns the project.
4. Allow Autonomous Deployments turned on for the target environment (see Catalog Settings). This applies when no person started the deployment.

Imbi refuses a service account that does not have integration:act-as-service with 403 and the error service_credential_forbidden. A platform administrator flag does not bypass this rule. Imbi gives integration:act-as-service to no seeded role except admin. Grant it to the role of each service account that must deploy. For example, the imbi-workflows role does not have it.

If the integration has no usable credential, Imbi returns 503 with the error no_service_credential.

In this release, only the deployment capability uses this fallback.

Login providers¶

A login provider is an integration of a plugin whose identity capability can sign users in: google, github, oidc, and aws. A login provider belongs to no organization, because users sign in before they select one. You manage login providers at Admin > Global Admin > Auth Providers, not on the Integrations page. See Authentication.

Related pages¶

• Plugins: one page for each plugin
• Webhooks: webhooks and rules that call webhook-actions
• Authentication: login providers
• Roles and permissions
• Authoring Plugins: the plugin contracts