> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Integration
> Creates a new integration instance within an organization.
`Unary` ยท [`Integrations`](/docs/api-reference/generated/integration/overview)
Creates a new integration instance within an organization.
Use this method to:
* Instantiate an integration for an organization
* Configure integration-specific settings
* Enable integration capabilities
## Endpoint
```text theme={null}
POST /api/gitpod.v1.IntegrationService/CreateIntegration
```
Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain.
## Request example
```bash cURL theme={null}
export ONA_HOST=https://app.ona.com
export ONA_API_KEY=
curl --request POST \
--url "$ONA_HOST/api/gitpod.v1.IntegrationService/CreateIntegration" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"integrationDefinitionId": ""
}'
```
```python Python theme={null}
import gitpod.v1.integration_pb2 as integration_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = integration_pb2.CreateIntegrationRequest(
integration_definition_id="",
)
response = ona.services.integration.create_integration(request)
print(response)
```
```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { CreateIntegrationRequestSchema } from "@gitpod/sdk/gitpod/v1/integration_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(CreateIntegrationRequestSchema, {
integrationDefinitionId: "",
});
const response = await ona.services.integration.createIntegration(request);
console.log(response);
}
main().catch(console.error);
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
"connectrpc.com/connect"
"github.com/gitpod-io/gitpod-sdk-go/sdk"
gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
)
func main() {
ona, err := sdk.NewFromEnv()
if err != nil {
log.Fatal(err)
}
request := connect.NewRequest(&gitpodpb.CreateIntegrationRequest{
IntegrationDefinitionId: "",
})
response, err := ona.Services.Integration.CreateIntegration(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"integrationDefinitionId": ""
}
```
## Request
`gitpod.v1.CreateIntegrationRequest`
| Field | Type | Required | Description |
| ------------------------- | ----------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `integrationDefinitionId` | string | No | integration\_definition\_id references the integration definition ID. Optional for custom integrations - when empty, name and host are required. |
| `runnerId` | string | No | runner\_id is optional and immutable - if provided, restricts integration to specific runner Constraints: `ignore=1, string.uuid=true`. |
| `enabled` | boolean | No | enabled indicates if this integration is enabled |
| `capabilities` | [IntegrationCapabilities](#type-gitpod-v1-integration-capabilities) | No | capabilities defines which capabilities are enabled for this integration |
| `auth` | [IntegrationAuthentication](#type-gitpod-v1-integration-authentication) | No | auth defines which authentication methods are enabled for this integration |
| `host` | string | No | host is the hostname for this integration (e.g., "linear.app") - optional, derived from MCP URL for custom integrations Constraints: `string.max_len=255`. |
| `name` | string | No | name is the display name for custom integrations. Required when integration\_definition\_id is empty. Constraints: `string.max_len=255`. |
| `description` | string | No | description is the description for custom integrations. Constraints: `string.max_len=500`. |
| `categories` | array of [IntegrationCategory](#enum-gitpod-v1-integration-category) | No | categories classifies this integration for filtering and display |
## Response
`gitpod.v1.CreateIntegrationResponse`
| Field | Type | Required | Description |
| ------------- | ------------------------------------------ | -------- | ----------------------------- |
| `integration` | [Integration](#type-gitpod-v1-integration) | Yes | Constraints: `required=true`. |
## Related types
Integration represents an instantiated integration within an organization
`gitpod.v1.Integration`
| Field | Type | Required | Description |
| ------------------------- | ------------------------------------------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | No | id is the unique identifier for this integration instance |
| `organizationId` | string | No | organization\_id is the organization this integration belongs to |
| `integrationDefinitionId` | string | No | integration\_definition\_id references the integration definition ID. Empty for custom integrations that don't have a backing definition. |
| `enabled` | boolean | No | enabled indicates if this integration is currently enabled |
| `capabilities` | [IntegrationCapabilities](#type-gitpod-v1-integration-capabilities) | No | capabilities defines which capabilities are enabled for this integration |
| `runnerId` | string | No | runner\_id - if set, restricts integration to specific runner |
| `auth` | [IntegrationAuthentication](#type-gitpod-v1-integration-authentication) | No | auth defines which authentication methods are enabled for this integration |
| `host` | string | No | host is the hostname for this integration (e.g., "linear.app") - optional, inherits from definition |
| `name` | string | No | name is the display name. For definition-backed integrations, resolved from the definition. |
| `description` | string | No | description of the integration. For definition-backed integrations, resolved from the definition. |
| `iconUrl` | string | No | icon\_url is the URL for this integration's icon. Resolved from the definition for definition-backed integrations. |
| `categories` | array of [IntegrationCategory](#enum-gitpod-v1-integration-category) | No | categories classifies this integration for filtering and display. For definition-backed integrations, inherits from the definition unless overridden. |
| `externalInstallation` | [IntegrationExternalInstallation](#type-gitpod-v1-integration-external-installation) | No | external\_installation identifies the provider-side app installation, when known. |
IntegrationAPIKeyConfig defines API key authentication configuration
`gitpod.v1.IntegrationAPIKeyConfig`
This message has no fields.
IntegrationAgentClientCapability indicates the integration supports agent client functionality.
Used by integrations that receive external events and create agent sessions.
IntegrationAgentClientCapability indicates the integration supports agent client functionality.
Secrets (webhook signing secret, API key) are stored in IntegrationProprietaryAppConfig
within the encrypted auth column.
`gitpod.v1.IntegrationAgentClientCapability`
| Field | Type | Required | Description |
| ------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `severityThreshold` | string | No | severity\_threshold controls the minimum incident severity that triggers an agent session. Values: "SEV1", "SEV2", "SEV3", or empty (all). |
| `defaultProjectId` | string | No | default\_project\_id is the Ona project to use when no project can be resolved from the incident context. Optional. Constraints: `ignore=1, string.uuid=true`. |
IntegrationAuthentication defines authentication requirements and options
`gitpod.v1.IntegrationAuthentication`
| Field | Type | Required | Description |
| ---------------- | ------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- |
| `requiresAuth` | boolean | No | requires\_auth indicates if authentication is required for this integration |
| `apiKey` | [IntegrationAPIKeyConfig](#type-gitpod-v1-integration-api-key-config) | No | api\_key configuration if API key authentication is supported |
| `oauth` | [IntegrationOAuthConfig](#type-gitpod-v1-integration-o-auth-config) | No | oauth configuration if OAuth authentication is supported |
| `proprietaryApp` | [IntegrationProprietaryAppConfig](#type-gitpod-v1-integration-proprietary-app-config) | No | proprietary configuration if supported |
IntegrationCapabilities defines what an integration can do
`gitpod.v1.IntegrationCapabilities`
| Field | Type | Required | Description |
| ------------------ | -------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mcp` | [IntegrationMCPCapability](#type-gitpod-v1-integration-mcp-capability) | No | mcp configuration for Model Context Protocol support |
| `contextParsing` | [IntegrationContextParsingCapability](#type-gitpod-v1-integration-context-parsing-capability) | No | context\_parsing configuration for context parsing support |
| `sourceCodeAccess` | [IntegrationSourceCodeAccessCapability](#type-gitpod-v1-integration-source-code-access-capability) | No | source\_code\_access configuration for source code access support |
| `login` | [IntegrationLoginCapability](#type-gitpod-v1-integration-login-capability) | No | login configuration for login/authentication support |
| `agentClient` | [IntegrationAgentClientCapability](#type-gitpod-v1-integration-agent-client-capability) | No | agent\_client configuration for agent client functionality support |
| `scmPrEvents` | [IntegrationScmPrEventsCapability](#type-gitpod-v1-integration-scm-pr-events-capability) | No | scm\_pr\_events indicates the integration can act as a source of PR events for automation triggers (e.g., pull\_request opened/updated webhooks). |
IntegrationContextParsingCapability defines context parsing capability
`gitpod.v1.IntegrationContextParsingCapability`
This message has no fields.
`gitpod.v1.IntegrationExternalInstallation`
| Field | Type | Required | Description |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
| `id` | string | No | id is the provider-assigned installation ID. |
| `accountName` | string | No | account\_name is the provider account or organization login associated with the installation. |
| `accountType` | string | No | account\_type is the provider account kind, when known. |
IntegrationLoginCapability defines login/authentication capability
`gitpod.v1.IntegrationLoginCapability`
This message has no fields.
IntegrationMCPCapability defines Model Context Protocol capability
`gitpod.v1.IntegrationMCPCapability`
| Field | Type | Required | Description |
| ----- | ------ | -------- | ---------------------------------------------------------------------------------- |
| `url` | string | No | url is the remote server URL for the MCP server Constraints: `string.max_len=255`. |
IntegrationOAuthConfig defines OAuth-specific configuration
`gitpod.v1.IntegrationOAuthConfig`
| Field | Type | Required | Description |
| --------------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `authUrl` | string | No | auth\_url is the OAuth authorization endpoint URL |
| `tokenUrl` | string | No | token\_url is the OAuth token endpoint URL |
| `scopes` | array of string | No | scopes are the OAuth scopes to request |
| `clientId` | string | No | client\_id is the OAuth client ID (optional if dynamic\_registration is enabled) |
| `clientSecret` | string | No | client\_secret is the OAuth client secret (optional for public clients) |
| `redirectUrl` | string | No | redirect\_url is the OAuth callback/redirect URL |
| `dynamicRegistration` | boolean | No | dynamic\_registration enables RFC 7591 OAuth 2.0 Dynamic Client Registration. When enabled, client credentials are obtained automatically from the authorization server's registration endpoint (discovered via RFC 8414 metadata). When disabled (default), client\_id and client\_secret must be pre-configured. |
| `authParams` | map of string to string | No | auth\_params are additional query parameters to include in the OAuth authorization URL. Use comma-separated values for multi-value params (e.g., "search:read,chat:write" for Slack's user\_scope). |
IntegrationProprietaryAppConfig defines proprietary application integration configuration.
Used for app installations that interact with Ona (e.g., GitHub Apps, Linear agent apps).
`gitpod.v1.IntegrationProprietaryAppConfig`
| Field | Type | Required | Description |
| --------------- | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientId` | string | No | client\_id is the app client ID |
| `clientSecret` | string | No | client\_secret is the app client secret |
| `webhookSecret` | string | No | webhook\_secret is the secret used to verify webhook signatures from the app provider |
| `authParams` | map of string to string | No | auth\_params are additional OAuth authorization parameters to include in the auth URL. Example: \{"actor": "app"} for Linear agent installations. |
| `appScopes` | array of string | No | app\_scopes are OAuth scopes to request when using app installation flows. If not set, falls back to the standard OAuth scopes. |
| `tokenUrl` | string | No | token\_url is the OAuth token exchange endpoint for app installation flows. If not set, falls back to the standard oauth.token\_url. Slack requires a different token endpoint for app-level vs user-level flows. |
| `appId` | string | No | app\_id is the application identifier assigned by the provider (e.g., GitHub App ID). Used to authenticate as the application itself. |
| `privateKey` | string | No | private\_key is the PEM-encoded private key used to sign JWTs for app authentication. This is sensitive and will be censored in API responses. |
| `appSlug` | string | No | app\_slug is the URL-friendly identifier assigned by the provider (e.g., GitHub App slug). Used to construct installation URLs like [https://github.com/apps/\{app\_slug\}/installations/new](https://github.com/apps/\{app_slug\}/installations/new). |
| `apiKey` | string | No | api\_key is the provider API key used to post updates back to the external service. Stored encrypted, censored in API responses. |
IntegrationScmPrEventsCapability indicates the integration can deliver
pull request webhook events (opened, updated, etc.) for automation triggers.
`gitpod.v1.IntegrationScmPrEventsCapability`
This message has no fields.
IntegrationSourceCodeAccessCapability defines source code access capability
`gitpod.v1.IntegrationSourceCodeAccessCapability`
This message has no fields.
IntegrationCategory classifies integrations for filtering and display.
| Value | Number | Description |
| ------------------------------------------ | -----: | ----------- |
| `INTEGRATION_CATEGORY_UNSPECIFIED` | 0 | |
| `INTEGRATION_CATEGORY_SOURCE_CONTROL` | 1 | |
| `INTEGRATION_CATEGORY_COMMUNICATION` | 2 | |
| `INTEGRATION_CATEGORY_PROJECT_MANAGEMENT` | 3 | |
| `INTEGRATION_CATEGORY_OBSERVABILITY` | 4 | |
| `INTEGRATION_CATEGORY_DATA_ANALYTICS` | 5 | |
| `INTEGRATION_CATEGORY_KNOWLEDGE` | 6 | |
| `INTEGRATION_CATEGORY_MCP` | 7 | |
| `INTEGRATION_CATEGORY_AUTOMATION_TRIGGERS` | 8 | |
| `INTEGRATION_CATEGORY_AI` | 9 | |