Hassann

Posted on Aug 31 Originally published at apidog.com

How to Connect a GHE.com Repository to Apidog

Connect Apidog to GitHub Enterprise Cloud Data Residency Tenants

Apidog can connect to GitHub Enterprise Cloud data-residency tenants hosted on dedicated *.ghe.com domains. After an Organization Admin configures the tenant and OAuth App, authorized project users can connect repositories and use supported OpenAPI import, backup, and synchronization workflows.

Try Apidog today

This integration supports GitHub Enterprise Cloud data-residency SaaS tenants only. It does not support GitHub Enterprise Server or arbitrary custom GitHub domains.

Before you start

You need:

An Apidog Enterprise organization with access to the integration
Organization Admin permission in Apidog
A GitHub Enterprise Cloud data-residency tenant on a root *.ghe.com domain, such as https://company.ghe.com
Permission to create an OAuth App on that tenant
Access to the GitHub organizations, repositories, and branches you plan to connect

Users who connect repositories must also have the required project-level Git connection permission in Apidog.

Step 1: Create an OAuth App on the GHE.com tenant

Sign in to your organization's GHE.com tenant.
Open the OAuth Apps settings.
Create a new OAuth App.
Enter an identifiable application name.
Set the homepage URL to https://apidog.com/?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation.
Set the authorization callback URL to https://api.apidog.com/passport/github/callback.
Register the OAuth App.
Copy the Client ID.
Generate and securely copy the Client Secret.

The callback URL must match the documented Apidog URL exactly.

Store the Client Secret in your approved secret-management system. Never place it in a screenshot, ticket, or shared document.

Step 2: Configure the GHE.com tenant in Apidog

Only an Organization Admin can configure or clear this integration.

Open the Apidog organization.
Go to Organization Settings.
Open GitHub Integration.
Find GitHub Enterprise Cloud Data Residency and select Configure.

Enter the GHE.com host URL, for example https://company.ghe.com.
Select OAuth App as the authentication method.
Enter the OAuth App Client ID.
Enter the OAuth App Client Secret.
Save the configuration.

Configure the tenant host and OAuth App credentials at the organization level.

After saving, Apidog displays the configured host URL. The Client Secret is not displayed or prefilled again.

When editing the configuration, leave the Client Secret field empty to keep the existing secret. Enter a new value only when rotating it.

Step 3: Connect a repository from an Apidog project

After the organization-level configuration is complete:

Open the required Apidog project.
Start a Git connection or Git import workflow.
Select GitHub Enterprise Cloud.
Continue to the authorization page on the configured GHE.com tenant.
Sign in and authorize the OAuth App.
Select the GitHub organization.
Select the repository and branch.
Complete the connection.

Authorization is performed on the configured GHE.com tenant, not on standard github.com.

If an expected organization or repository is missing, check the GitHub account's access and OAuth App authorization before changing the Apidog organization settings.

Step 4: Import an OpenAPI file

To import an OpenAPI or Swagger file from the connected repository:

Start an import workflow in the Apidog project.
Choose OpenAPI/Swagger.
Select Git Repository.
Choose the GitHub organization, repository, branch, and file.
Select Continue.
Choose an existing target Module or create a new one.
Complete the import.
Review the imported endpoints and schemas before accepting the result.

Select the repository, branch, and specification file required by the project.

Use a non-production project for the first import, especially when the target module already contains API definitions.

Step 5: Choose the ongoing synchronization workflow

A repository connection can support different workflows. Choose one source of truth and document it for the team.

Workflow	Use it when	Important behavior
Manual import	Changes are brought into Apidog only when requested	Review each import and target module
Scheduled Import	The Git file remains the source and Apidog should refresh it at an interval	Runs through the local client or a self-hosted Runner according to the configured execution mode
Backup to Git	Apidog content should be written to a repository file	Configure the repository, branch, and target file path; automatic backups run during a randomly scheduled off-peak period at night
Spec-first Mode	The specification file is the source of truth and the team edits through a Git-oriented workflow	This mode is currently beta; webhook installation usually requires repository admin permission

Do not configure two opposing automated workflows against the same file without a clear conflict-resolution rule.

Configure Backup to Git

Create or select the Git connection in project settings.
Open Module Overview > API Specification.
Add or select the OpenAPI specification.
Enable Backup to Git Repository.
Choose the repository connection, branch, and target file path.
Save the configuration.

For a repository-driven source of truth, use Scheduled Import or review Spec-first Mode.

Step 6: Verify the integration

Run a small end-to-end test:

Confirm authorization opens the configured GHE.com tenant.
Confirm only the expected organizations and repositories are available.
Import a known OpenAPI file and compare the result with the source.
Test the selected backup or synchronization direction in a disposable branch.
Confirm branch protection and repository permissions behave as expected.
Review synchronization logs and errors.
Rotate the OAuth App Client Secret and confirm the documented update process works.

If webhook synchronization is used, verify that the installer has repository admin permission and that the expected push event triggers synchronization.

Update or clear the organization settings

Organization Admins can edit the host URL or Client ID and rotate the Client Secret by entering a new value.

To remove the organization-level configuration:

Open Organization Settings > GitHub Integration.
Find the data-residency integration.
Select Clear settings.

After the settings are cleared, users cannot create new GitHub Enterprise Cloud connections until the integration is configured again. Existing connections may require reconfiguration or reauthorization depending on token status and organization settings.

Troubleshooting

Problem	What to check
The integration option is unavailable	Confirm that the organization has access to the Enterprise feature and that you are an Organization Admin.
OAuth returns a callback error	Confirm that the OAuth App callback is exactly `https://api.apidog.com/passport/github/callback`.
Authorization opens github.com	Confirm that the organization-level host is the intended root `*.ghe.com` tenant.
A repository is missing	Check the authorized GitHub user's organization and repository access, as well as any OAuth restrictions.
A project user cannot create a connection	Confirm that the user has the required project-level Git connection permission.
Import or synchronization fails	Check the selected branch, file path, file format, repository permissions, and synchronization logs.

Security and data-residency boundaries

Only Organization Admins can configure or clear the GHE.com integration.
The Client Secret is not displayed after configuration.
Project permissions still control who can create or update Git connections.
OAuth authorization occurs through the configured GHE.com tenant.
Requested OAuth permissions can include access needed to read organizations, repositories, branches, and import files; write backups; and manage repository hooks when required by a synchronization workflow.

Connecting a data-residency tenant does not by itself prove that every category of GitHub or Apidog-related data remains in one region. GitHub documents the data covered by its residency offering and relevant exceptions. Apidog is a separate connected service with its own storage and deployment model. Review both vendors' current documentation as part of a data-residency or compliance assessment.

DEV Community