> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/api-documentation/api-reference/api--connectors/mutations/onboard-self-hosted-git-hub-app-installation.md).

# onboardSelfHostedGitHubAppInstallation

Onboards an additional installation of an already-registered self-hosted GitHub App; oxAppId is only needed when the same GitHub App has more than one registration.

### Examples

{% tabs %}
{% tab title="GraphQL" %}

```graphql
mutation OnboardSelfHostedGitHubAppInstallation($gitHubAppId: String!, $installationId: Int!, $oxAppId: String, $credentialsName: String) {
  onboardSelfHostedGitHubAppInstallation(gitHubAppId: $gitHubAppId, installationId: $installationId, oxAppId: $oxAppId, credentialsName: $credentialsName) {
    connector {
      id
      name
      displayName
      description
      hostURL
      iconURL
      family
      credentialsType
      credentialsTypes
      brokerSupportCredentialsTypes
      disabledMultiCredentialsTypes
      credentials {
        ... on UserPasswordOnlyCredentials {
          name
          password
          credentialsId
          credentialsName
          tokenExpirationDate
          invalidReason
          credentialsType
          isCertChecksDisabled
          hostURL
          iv
          monitoredResources
          monitorAllResources
          monitorAllNewlyCreatedResources
          brokerUsername
          brokerPassword
          brokerEnabled
          brokerHost
          brokerPort
        }
      }
      isConfigured
      isResourceAvailable
      ffKeyResourceAvailable
      resourceOptions {
        resourceName
        hideMonitorNewResourcesCheckbox
        showSettingsPerResource
      }
      resources {
        type
      }
      isOxBuiltIn
      isOpenSource
      openSourceWebsiteUrl
      openSourceLicense
      openSourceAuthor
      defaultEnabled
      comingSoon
      isDemoEnabled
      aliasFor
      identityProviderInfo {
        baseURL
        urlParams
        scope
        configText
        user_scope
      }
      gitHubAppInfo {
        baseURL
        urlPath
        configText
      }
      bitbucketAppInfo {
        baseURL
        queryParameters
        configText
      }
      awsCloudFormationInfo {
        baseURL
        urlParams
      }
      awsCloudFormationOrganizationInfo {
        baseURL
        urlParams
      }
      oidcIssuerUrl
      connectionInstructions {
        type
        title
        details
        linksToDocs {
          href
          title
        }
        permissions
        hostURL
      }
      isDiscovered
      isEmptyOfRepos
      isDevelopment
      connectorExplanation
      optionalInputFields {
        name
        credsTypes
        inputType
        key
        ffKey
        value
      }
      conditionalOptionalTabs {
        tabTitle
        tabInputs {
          inputType
          inputTitle
          inputName
        }
      }
      dependsOn
      disabledBy
      externalLink
      textExternalLink
      internalLink
      textInternalLink
      ffKey
      beta
      supportedDisabledCertChecksTypes
      enableMultiCredentials
      requiresHostURL
    }
  }
}
```

#### Variables

This is an example input showing all available input fields. Only fields marked as required in the schema are mandatory.

```json
{
  "gitHubAppId": "example",
  "installationId": 42,
  "oxAppId": "example",
  "credentialsName": "example"
}
```

{% endtab %}

{% tab title="cURL" %}

```shell
curl -X POST \
https://api.cloud.ox.security/api/apollo-gateway \
-H 'Content-Type: application/json' \
-H 'Authorization: YOUR_API_TOKEN' \
-d '{
 "query": "mutation OnboardSelfHostedGitHubAppInstallation($gitHubAppId: String!, $installationId: Int!, $oxAppId: String, $credentialsName: String) { onboardSelfHostedGitHubAppInstallation(gitHubAppId: $gitHubAppId, installationId: $installationId, oxAppId: $oxAppId, credentialsName: $credentialsName) { connector { id name displayName description hostURL iconURL family credentialsType credentialsTypes brokerSupportCredentialsTypes disabledMultiCredentialsTypes credentials { ... on UserPasswordOnlyCredentials { name password credentialsId credentialsName tokenExpirationDate invalidReason credentialsType isCertChecksDisabled hostURL iv monitoredResources monitorAllResources monitorAllNewlyCreatedResources brokerUsername brokerPassword brokerEnabled brokerHost brokerPort } } isConfigured isResourceAvailable ffKeyResourceAvailable resourceOptions { resourceName hideMonitorNewResourcesCheckbox showSettingsPerResource } resources { type } isOxBuiltIn isOpenSource openSourceWebsiteUrl openSourceLicense openSourceAuthor defaultEnabled comingSoon isDemoEnabled aliasFor identityProviderInfo { baseURL urlParams scope configText user_scope } gitHubAppInfo { baseURL urlPath configText } bitbucketAppInfo { baseURL queryParameters configText } awsCloudFormationInfo { baseURL urlParams } awsCloudFormationOrganizationInfo { baseURL urlParams } oidcIssuerUrl connectionInstructions { type title details linksToDocs { href title } permissions hostURL } isDiscovered isEmptyOfRepos isDevelopment connectorExplanation optionalInputFields { name credsTypes inputType key ffKey value } conditionalOptionalTabs { tabTitle tabInputs { inputType inputTitle inputName } } dependsOn disabledBy externalLink textExternalLink internalLink textInternalLink ffKey beta supportedDisabledCertChecksTypes enableMultiCredentials requiresHostURL } } }",
 "variables": {
    "gitHubAppId": "example",
    "installationId": 42,
    "oxAppId": "example",
    "credentialsName": "example"
  }
}'
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const query = 'mutation OnboardSelfHostedGitHubAppInstallation($gitHubAppId: String!, $installationId: Int!, $oxAppId: String, $credentialsName: String) { onboardSelfHostedGitHubAppInstallation(gitHubAppId: $gitHubAppId, installationId: $installationId, oxAppId: $oxAppId, credentialsName: $credentialsName) { connector { id name displayName description hostURL iconURL family credentialsType credentialsTypes brokerSupportCredentialsTypes disabledMultiCredentialsTypes credentials { ... on UserPasswordOnlyCredentials { name password credentialsId credentialsName tokenExpirationDate invalidReason credentialsType isCertChecksDisabled hostURL iv monitoredResources monitorAllResources monitorAllNewlyCreatedResources brokerUsername brokerPassword brokerEnabled brokerHost brokerPort } } isConfigured isResourceAvailable ffKeyResourceAvailable resourceOptions { resourceName hideMonitorNewResourcesCheckbox showSettingsPerResource } resources { type } isOxBuiltIn isOpenSource openSourceWebsiteUrl openSourceLicense openSourceAuthor defaultEnabled comingSoon isDemoEnabled aliasFor identityProviderInfo { baseURL urlParams scope configText user_scope } gitHubAppInfo { baseURL urlPath configText } bitbucketAppInfo { baseURL queryParameters configText } awsCloudFormationInfo { baseURL urlParams } awsCloudFormationOrganizationInfo { baseURL urlParams } oidcIssuerUrl connectionInstructions { type title details linksToDocs { href title } permissions hostURL } isDiscovered isEmptyOfRepos isDevelopment connectorExplanation optionalInputFields { name credsTypes inputType key ffKey value } conditionalOptionalTabs { tabTitle tabInputs { inputType inputTitle inputName } } dependsOn disabledBy externalLink textExternalLink internalLink textInternalLink ffKey beta supportedDisabledCertChecksTypes enableMultiCredentials requiresHostURL } } }';

fetch("https://api.cloud.ox.security/api/apollo-gateway", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_TOKEN"
  },
  body: JSON.stringify({
    query: query,
    // This is an example input showing all available input fields. Only fields marked as required in the schema are mandatory.
    variables: {
      gitHubAppId: "example",
      installationId: 42,
      oxAppId: "example",
      credentialsName: "example"
    }
  })
})
.then(response => response.json())
.then(result => console.log(JSON.stringify(result, null, 2)))
.catch(error => console.error('Error:', error));
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

query = 'mutation OnboardSelfHostedGitHubAppInstallation($gitHubAppId: String!, $installationId: Int!, $oxAppId: String, $credentialsName: String) { onboardSelfHostedGitHubAppInstallation(gitHubAppId: $gitHubAppId, installationId: $installationId, oxAppId: $oxAppId, credentialsName: $credentialsName) { connector { id name displayName description hostURL iconURL family credentialsType credentialsTypes brokerSupportCredentialsTypes disabledMultiCredentialsTypes credentials { ... on UserPasswordOnlyCredentials { name password credentialsId credentialsName tokenExpirationDate invalidReason credentialsType isCertChecksDisabled hostURL iv monitoredResources monitorAllResources monitorAllNewlyCreatedResources brokerUsername brokerPassword brokerEnabled brokerHost brokerPort } } isConfigured isResourceAvailable ffKeyResourceAvailable resourceOptions { resourceName hideMonitorNewResourcesCheckbox showSettingsPerResource } resources { type } isOxBuiltIn isOpenSource openSourceWebsiteUrl openSourceLicense openSourceAuthor defaultEnabled comingSoon isDemoEnabled aliasFor identityProviderInfo { baseURL urlParams scope configText user_scope } gitHubAppInfo { baseURL urlPath configText } bitbucketAppInfo { baseURL queryParameters configText } awsCloudFormationInfo { baseURL urlParams } awsCloudFormationOrganizationInfo { baseURL urlParams } oidcIssuerUrl connectionInstructions { type title details linksToDocs { href title } permissions hostURL } isDiscovered isEmptyOfRepos isDevelopment connectorExplanation optionalInputFields { name credsTypes inputType key ffKey value } conditionalOptionalTabs { tabTitle tabInputs { inputType inputTitle inputName } } dependsOn disabledBy externalLink textExternalLink internalLink textInternalLink ffKey beta supportedDisabledCertChecksTypes enableMultiCredentials requiresHostURL } } }'

response = requests.post(
  "https://api.cloud.ox.security/api/apollo-gateway",
  headers={
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_TOKEN"
  },
  json={
    "query": query,
    # This is an example input showing all available input fields. Only fields marked as required in the schema are mandatory.
    "variables": {
      "gitHubAppId": "example",
      "installationId": 42,
      "oxAppId": "example",
      "credentialsName": "example"
    }
  }
)

if response.status_code == 200:
    result = response.json()
    print(result)
else:
    print(f"Error: {response.status_code}")
    print(response.text)
```

{% endtab %}
{% endtabs %}

### Arguments

You can use the following argument(s) to customize your `onboardSelfHostedGitHubAppInstallation` mutation.

| Argument                                                                            | Description | Supported fields |
| ----------------------------------------------------------------------------------- | ----------- | ---------------- |
| gitHubAppId `String!` <mark style="color:red;background-color:red;">required</mark> |             |                  |
| installationId `Int!` <mark style="color:red;background-color:red;">required</mark> |             |                  |
| oxAppId `String`                                                                    |             |                  |
| credentialsName `String`                                                            |             |                  |

### Fields

Return type: [`ConnectorResponse`](https://docs.ox.security/api-documentation/api-reference/api--connectors/types/objects/connector-response.md)

You can use the following field(s) to specify what information your `onboardSelfHostedGitHubAppInstallation` mutation will return. Please note that some fields may have their own subfields.

| Field                                                                                                                        | Description      | Supported fields                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| connector [`Connector`](https://docs.ox.security/api-documentation/api-reference/api--connectors/types/objects/connector.md) | Connector object | <p>id <code>String</code><br>name <code>String</code><br>displayName <code>String</code><br>description <code>String</code><br>hostURL <code>String</code><br>iconURL <code>String</code><br>family <code>String</code><br>credentialsType <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/enums/credentials-type.md"><code>CredentialsType</code></a><br>credentialsTypes <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/enums/credentials-type.md"><code>\[CredentialsType]</code></a><br>brokerSupportCredentialsTypes <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/enums/credentials-type.md"><code>\[CredentialsType]</code></a><br>disabledMultiCredentialsTypes <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/enums/credentials-type.md"><code>\[CredentialsType]</code></a><br>credentials <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/unions/credential.md"><code>\[Credential]</code></a><br>isConfigured <code>Boolean</code><br>isResourceAvailable <code>Boolean</code><br>ffKeyResourceAvailable <code>String</code><br>resourceOptions <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/objects/resource-options.md"><code>ResourceOptions</code></a><br>resources <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/objects/resource-item.md"><code>\[ResourceItem]</code></a><br>isOxBuiltIn <code>Boolean</code><br>isOpenSource <code>Boolean</code><br>openSourceWebsiteUrl <code>String</code><br>openSourceLicense <code>String</code><br>openSourceAuthor <code>String</code><br>defaultEnabled <code>Boolean</code><br>comingSoon <code>Boolean</code><br>isDemoEnabled <code>Boolean</code><br>aliasFor <code>String</code><br>identityProviderInfo <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/objects/identity-provider-info.md"><code>IdentityProviderInfo</code></a><br>gitHubAppInfo <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/objects/git-hub-app-info.md"><code>GitHubAppInfo</code></a><br>bitbucketAppInfo <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/objects/bitbucket-app-info.md"><code>BitbucketAppInfo</code></a><br>awsCloudFormationInfo <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/objects/aws-cloud-formation-info.md"><code>AWSCloudFormationInfo</code></a><br>awsCloudFormationOrganizationInfo <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/objects/aws-cloud-formation-info.md"><code>AWSCloudFormationInfo</code></a><br>oidcIssuerUrl <code>String</code><br>connectionInstructions <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/objects/connection-instructions.md"><code>\[ConnectionInstructions]</code></a><br>isDiscovered <code>Boolean</code><br>isEmptyOfRepos <code>Boolean</code><br>isDevelopment <code>Boolean</code><br>connectorExplanation <code>String</code><br>optionalInputFields <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/objects/optional-connector-input.md"><code>\[OptionalConnectorInput]</code></a><br>conditionalOptionalTabs <a href="https://docs.ox.security/api-documentation/api-reference/api--connectors/types/objects/conditional-optional-tabs.md"><code>\[ConditionalOptionalTabs]</code></a><br>dependsOn <code>String</code><br>disabledBy <code>\[String]</code><br>externalLink <code>String</code><br>textExternalLink <code>String</code><br>internalLink <code>String</code><br>textInternalLink <code>String</code><br>ffKey <code>String</code><br>beta <code>Boolean</code><br>supportedDisabledCertChecksTypes <code>\[String]</code><br>enableMultiCredentials <code>Boolean</code><br>requiresHostURL <code>Boolean</code></p> |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ox.security/api-documentation/api-reference/api--connectors/mutations/onboard-self-hosted-git-hub-app-installation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
