# Git Connection Configuration

## Overview

The **Git Connection and Backup** functionality enables you to automatically back up your API documentation to Git repositories hosted on **GitHub** or **GitLab** platforms. This feature is supported for both SaaS and enterprise versions of these platforms, depending on the environment variables you configure.


:::tip[]
**Version Requirement:** This feature requires Apidog On-Premises image version 2.7.38 or later.
:::

## GitHub App Configuration (Recommended)

:::tip[]
**Version Requirement:** This feature requires Apidog On-Premises image version **2.7.72** or later.

**GitHub App vs OAuth2 App:** GitHub App is the newer recommended approach for GitHub integration. It provides more granular permissions and better security. The OAuth2 App configuration below is maintained for backward compatibility with existing setups. Both can be enabled simultaneously.
:::

To integrate with a GitHub App, you need to create a new GitHub App in your GitHub settings. For the GitHub SaaS version, visit:

  - https://github.com/settings/apps

### Creating a GitHub App

1. Click **New GitHub App** and configure the following settings:

   - **GitHub App name:** Choose a descriptive name (e.g., `Apidog Git Integration`)
   - **Homepage URL:** `https://your-apidog-domain.com/`
   - **Callback URL:** `https://your-apidog-domain.com/passport/github/callback`
   - **Request user authorization (OAuth) during installation:** ✅ Enable
   - **Post installation — Redirect on update:** ✅ Enable
   - **Webhook — Active:** ❌ Disable

2. Set the following **permissions**:

   - **Repository permissions:**
     - Administration: **Read & write**
     - Contents: **Read & write**
     - Metadata: **Read-only**
     - Webhooks: **Read & write**
   - **Organization permissions:**
     - Members: **Read-only**
   - **Account permissions:** None required

3. Under **Where can this GitHub App be installed?**, select **Any account**.

4. Click **Create GitHub App**.

5. After creation, note the **App ID** and **App slug** (from the URL). Then generate a **Client secret** under the app settings and note the **Client ID**.

### Environment Variables

| Environment Variable                            | Description                                     | Default Value              | Notes                                                                                          |
| ----------------------------------------------- | ----------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------- |
| `GIT_CONNECTION_GITHUB_APP_ENABLE`              | Whether to enable GitHub App git connection      | `false`                    | Set to `true` to enable GitHub App integration                                                 |
| `GITHUB_APP_AUTH_HOST`                          | GitHub App authentication host URL               | `https://github.com`       | Use `https://github.com` for SaaS or your enterprise GitHub host                               |
| `GITHUB_APP_API_HOST`                           | GitHub App API host URL                          | `https://api.github.com`   | Use `https://api.github.com` for SaaS or enterprise host with `/api/v3`                        |
| `GITHUB_APP_CLIENT_ID`                          | GitHub App client ID                             | -                          | Required — from GitHub App settings                                                            |
| `GITHUB_APP_CLIENT_SECRET`                      | GitHub App client secret                         | -                          | Required — from GitHub App settings                                                            |
| `GIT_CONNECTION_GITHUB_APP_REJECT_UNAUTHORIZED` | SSL certificate validation for GitHub App        | `false`                    | Set to `false` for self-signed certificates in enterprise environments                         |
| `GITHUB_APP_SLUG`                               | GitHub App slug identifier                       | -                          | The slug from your GitHub App URL (e.g., `my-apidog-app`)                                      |
| `GITHUB_APP_ID`                                 | GitHub App ID                                    | -                          | The numeric App ID from your GitHub App settings                                               |

### Configuration Example for GitHub SaaS Version
```
- name: GIT_CONNECTION_GITHUB_APP_ENABLE
  value: 'true'
- name: GITHUB_APP_AUTH_HOST
  value: 'https://github.com'
- name: GITHUB_APP_API_HOST
  value: 'https://api.github.com'
- name: GITHUB_APP_CLIENT_ID
  value: <your-github-app-client-id>
- name: GITHUB_APP_CLIENT_SECRET
  value: <your-github-app-client-secret>
- name: GIT_CONNECTION_GITHUB_APP_REJECT_UNAUTHORIZED
  value: 'false'
- name: GITHUB_APP_SLUG
  value: <your-github-app-slug>
- name: GITHUB_APP_ID
  value: <your-github-app-id>
```

### Configuration Example for GitHub Enterprise Version
```
- name: GIT_CONNECTION_GITHUB_APP_ENABLE
  value: 'true'
- name: GITHUB_APP_AUTH_HOST
  value: 'https://github.yourcompany.com'
- name: GITHUB_APP_API_HOST
  value: 'https://github.yourcompany.com/api/v3'
- name: GITHUB_APP_CLIENT_ID
  value: <your-enterprise-github-app-client-id>
- name: GITHUB_APP_CLIENT_SECRET
  value: <your-enterprise-github-app-client-secret>
- name: GIT_CONNECTION_GITHUB_APP_REJECT_UNAUTHORIZED
  value: 'false'
- name: GITHUB_APP_SLUG
  value: <your-enterprise-github-app-slug>
- name: GITHUB_APP_ID
  value: <your-enterprise-github-app-id>
```

## GitHub OAuth2 Configuration (Legacy)

To integrate with GitHub using an OAuth2 App, you need to create a new OAuth app in the GitHub settings. For the GitHub SaaS version, you can access the settings page using the following URL:

    - https://github.com/settings/developers.

<Background>
  ![image.png](https://api.apidog.com/api/v1/projects/384270/resources/362635/image-preview)
</Background>

When creating the OAuth app, set the Authorization callback URL to your Apidog On-Premises API domain, followed by `/passport/github/callback`.

For-example: `https://your-apidog-domain.com/passport/github/callback`


Once the app is created, take note of the **Client ID** and **Client Secret**, then configure the following environment variables:

| Environment Variable                        | Description                             | Default Value | Notes                                                                                                                            |
| ------------------------------------------- | --------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `GIT_CONNECTION_GITHUB_ENABLE`              | Whether to enable GitHub Git connection | `true`        | Set to `true` to enable GitHub integration                                                                                       |
| `GITHUB_AUTH_HOST`                          | GitHub authentication host URL          | -             | Use `https://github.com` for SaaS GitHub or your enterprise GitHub host                                                        |
| `GITHUB_API_HOST`                           | GitHub API host URL                     | -             | Use `https://api.github.com` for SaaS GitHub. Or use `GITHUB_AUTH_HOST` with `/api/v3` for enterprise version |
| `GITHUB_KEY`                                | GitHub OAuth application client ID      | -             | Required for GitHub OAuth authentication                                                                                         |
| `GITHUB_SECRET`                             | GitHub OAuth application client secret  | -             | Required for GitHub OAuth authentication                                                                                         |
| `GIT_CONNECTION_GITHUB_REJECT_UNAUTHORIZED` | SSL certificate validation for GitHub   | `true`        | Set to `false` for self-signed certificates in enterprise environments             |

### Configuration Example for GitHub SaaS Version
```
- name: GIT_CONNECTION_GITHUB_ENABLE
  value: 'true'
- name: GITHUB_AUTH_HOST
  value: 'https://github.com'
- name: GITHUB_API_HOST
  value: 'https://api.github.com'
- name: GITHUB_KEY
  value: <your-github-client-id>
- name: GITHUB_SECRET
  value: <your-github-client-secret>
- name: GIT_CONNECTION_GITHUB_REJECT_UNAUTHORIZED
  value: 'true'
```

### Configuration Example for GitHub Enterprise Version
```
- name: GIT_CONNECTION_GITHUB_ENABLE
  value: 'true'
- name: GITHUB_AUTH_HOST
  value: 'https://github.yourcompany.com'
- name: GITHUB_API_HOST
  value: 'https://github.yourcompany.com/api/v3'
- name: GITHUB_KEY
  value: <your-enterprise-github-client-id>
- name: GITHUB_SECRET
  value: <your-enterprise-github-client-secret>
- name: GIT_CONNECTION_GITHUB_REJECT_UNAUTHORIZED
  value: 'false'
```

## GitLab Configuration

To integrate with GitLab, create a new **OAuth app** in the GitLab settings. For the GitLab SaaS version, visit the following URL:
    - https://gitlab.com/-/user_settings/applications.

<Background>
  ![image.png](https://api.apidog.com/api/v1/projects/384270/resources/362625/image-preview)
</Background>

### Configuration Steps

1.  **Redirect Callback URL:** Set the callback URL to your Apidog On-Premises API domain, followed by `/api/v1/projects/git-connections/gitlab-callback`.

        Forexample:

        `https://your-apidog-domain.com/api/v1/projects/git-connections/gitlab-callback`

2. **Scopes:** Ensure that the `api` scope is selected.

3. Once the OAuth app is created, make a note of the **Application ID** and **Application Secret**. Then, configure the following environment variables:

| Environment Variable                            | Description                                | Default Value | Notes                                                                                                                                 |
| ----------------------------------------------- | ------------------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `GIT_CONNECTION_GITLAB_COM_ENABLE`              | Whether to enable GitLab.com connection    | `false`       | Set to `true` to enable GitLab.com integration                                                                                        |
| `GITLAB_COM_AUTH_HOST`                          | GitLab.com authentication host URL         | -             | Use `https://gitlab.com` for SaaS GitLab or your enterprise GitLab host                                                             |
| `GITLAB_COM_KEY`                                | GitLab.com OAuth application client ID     | -             | Required for GitLab OAuth authentication                                                                                              |
| `GITLAB_COM_SECRET`                             | GitLab.com OAuth application client secret | -             | Required for GitLab OAuth authentication                                                                                              |
| `GITLAB_SCOPE`                                  | GitLab OAuth scope permissions             | -             | Define required permissions (e.g., `api`, `read_user`, `read_repository`). Must match the scope configured in your GitLab application |
| `GITLAB_REDIRECT_URI`                           | GitLab OAuth redirect URI                  | -             | Must match the redirect URI configured in your GitLab application                                                                     |
| `GIT_CONNECTION_GITLAB_COM_REJECT_UNAUTHORIZED` | SSL certificate validation for GitLab.com  | `true`        | Set to `false` for self-signed certificates in enterprise environments                                                                |

### Configuration Example for GitLab SaaS Version
```
- name: GIT_CONNECTION_GITLAB_COM_ENABLE
  value: 'true'
- name: GITLAB_COM_AUTH_HOST
  value: 'https://gitlab.com'
- name: GITLAB_COM_KEY
  value: <your-gitlab-client-id>
- name: GITLAB_COM_SECRET
  value: <your-gitlab-client-secret>
- name: GITLAB_SCOPE
  value: 'api'
- name: GITLAB_REDIRECT_URI
  value: 'https://your-apidog-domain.com/api/v1/projects/git-connections/gitlab-callback'
- name: GIT_CONNECTION_GITLAB_COM_REJECT_UNAUTHORIZED
  value: 'true'
```

### Configuration Example for GitLab Enterprise Version
```
- name: GIT_CONNECTION_GITLAB_COM_ENABLE
  value: 'true'
- name: GITLAB_COM_AUTH_HOST
  value: 'https://gitlab.yourcompany.com'
- name: GITLAB_COM_KEY
  value: <your-enterprise-gitlab-client-id>
- name: GITLAB_COM_SECRET
  value: <your-enterprise-gitlab-client-secret>
- name: GITLAB_SCOPE
  value: 'api'
- name: GITLAB_REDIRECT_URI
  value: 'https://your-apidog-domain.com/api/v1/projects/git-connections/gitlab-callback'
- name: GIT_CONNECTION_GITLAB_COM_REJECT_UNAUTHORIZED
  value: 'false'
```