> ## 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 SCM Integration

> Creates a new SCM integration for a runner.

`Unary` · [`Runner Configurations`](/docs/api-reference/generated/runner-configuration/overview)

Creates a new SCM integration for a runner.

Use this method to:

* Configure source control access
* Set up repository integrations
* Enable code synchronization

### Examples

* Create GitHub integration:

  Sets up GitHub SCM integration.

  ```yaml theme={null}
  runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  scmId: "github"
  host: "github.com"
  oauthClientId: "client_id"
  oauthPlaintextClientSecret: "client_secret"
  ```

## Endpoint

```text theme={null}
POST /api/gitpod.v1.RunnerConfigurationService/CreateSCMIntegration
```

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

<CodeGroup>
  ```bash cURL theme={null}
  export ONA_HOST=https://app.ona.com
  export ONA_API_KEY=<your-token>

  curl --request POST \
    --url "$ONA_HOST/api/gitpod.v1.RunnerConfigurationService/CreateSCMIntegration" \
    --header "Authorization: Bearer $ONA_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
    "runnerId": "<runner-id>"
  }'
  ```

  ```python Python theme={null}
  import gitpod.v1.runner_configuration_pb2 as runner_configuration_pb2
  from ona_sdk import create_client_from_env

  ona = create_client_from_env()
  request = runner_configuration_pb2.CreateSCMIntegrationRequest(
      runner_id="<runner-id>",
  )
  response = ona.services.runner_configuration.create_scm_integration(request)
  print(response)
  ```

  ```typescript TypeScript theme={null}
  import { create } from "@bufbuild/protobuf";
  import { createClientFromEnv } from "@gitpod/sdk";
  import { CreateSCMIntegrationRequestSchema } from "@gitpod/sdk/gitpod/v1/runner_configuration_pb";

  async function main() {
    const ona = createClientFromEnv();
    const request = create(CreateSCMIntegrationRequestSchema, {
      runnerId: "<runner-id>",
    });
    const response = await ona.services.runnerConfiguration.createSCMIntegration(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.CreateSCMIntegrationRequest{
  		RunnerId: "<runner-id>",
  	})
  	response, err := ona.Services.RunnerConfiguration.CreateSCMIntegration(context.Background(), request)
  	if err != nil {
  		log.Fatal(err)
  	}
  	fmt.Println(response.Msg)
  }
  ```

  ```json Request body theme={null}
  {
    "runnerId": "<runner-id>"
  }
  ```
</CodeGroup>

## Request

`gitpod.v1.CreateSCMIntegrationRequest`

| Field                        | Type    | Required | Description                                                                                                                                                                                                                                                                                           |
| ---------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runnerId`                   | string  | No       | Constraints: `string.uuid=true`.                                                                                                                                                                                                                                                                      |
| `scmId`                      | string  | No       | scm\_id references the scm\_id in the runner's configuration schema that this integration is for                                                                                                                                                                                                      |
| `host`                       | string  | No       |                                                                                                                                                                                                                                                                                                       |
| `oauthClientId`              | string  | No       | oauth\_client\_id is the OAuth app's client ID, if OAuth is configured. If configured, oauth\_plaintext\_client\_secret must also be set.                                                                                                                                                             |
| `oauthPlaintextClientSecret` | string  | No       | oauth\_plaintext\_client\_secret is the OAuth app's client secret in clear text. This will first be encrypted with the runner's public key before being stored.                                                                                                                                       |
| `pat`                        | boolean | No       |                                                                                                                                                                                                                                                                                                       |
| `issuerUrl`                  | string  | No       | issuer\_url can be set to override the authentication provider URL, if it doesn't match the SCM host.                                                                                                                                                                                                 |
| `virtualDirectory`           | string  | No       | virtual\_directory is the virtual directory path for Azure DevOps Server (e.g., "/tfs"). This field is only used for Azure DevOps Server SCM integrations and should be empty for other SCM types. Azure DevOps Server APIs work without collection when PAT scope is 'All accessible organizations'. |

## Response

`gitpod.v1.CreateSCMIntegrationResponse`

| Field | Type   | Required | Description                                                                                    |
| ----- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| `id`  | string | No       | id is a uniquely generated identifier for the SCM integration Constraints: `string.uuid=true`. |