How Do You Connect Apidog to GitHub, GitLab ?

If your API specs live in Apidog but your source of truth lives in Git, connect them. Apidog Git integration lets you link a GitHub, GitLab, or Azure DevOps repository to your project, push OpenAPI specs into version control, and pull repository changes back into Apidog. The result: reviewable spec changes, Git history, and a backup outside the app.

Try Apidog today

This guide covers the Git providers Apidog supports, the two Git workflows available, and the implementation decisions you need to make: repository, branch, permissions, and recovery steps. If you only need the GitHub-specific walkthrough, see the dedicated guide on how to sync your OpenAPI spec to GitHub.

What Apidog Git integration does

Apidog supports two different Git workflows. Choose the one that matches how your team manages API specs.

1. Two-way sync with Spec-First Mode

Use this when your team treats the OpenAPI document like code.

You edit the OpenAPI YAML or JSON in Apidog, commit the change, and push it to the connected Git branch. If someone changes the spec in the repository, you pull those changes back into Apidog.

This is a real round trip:

Apidog <-> Git repository

Use it when you want:

• Pull requests for API spec changes
• Code review on OpenAPI diffs
• Git history for every API design change
• The ability to pull repo-side edits back into Apidog

2. Automatic Git backup

Use this when you want a versioned copy of your API specs without changing your daily workflow.

Apidog exports each module’s OpenAPI/Swagger file and pushes it to a repository on a schedule. This is one-way:

Apidog -> Git repository

Use it when you want:

• Scheduled backups
• Versioned API contract snapshots
• A recovery point outside Apidog
• No manual commit/push workflow

Capability	Direction	Trigger	Best for
Spec-First Mode sync	Two-way: push and pull	Manual commit/push, manual pull	Teams that treat API specs as code
Automatic Git backup	One-way: Apidog to Git	Scheduled, off-peak	Teams that want versioned backups

For the rest of this guide:

• Sync means the two-way Spec-First Mode workflow.
• Backup means the scheduled one-way export workflow.

Supported Git providers

Apidog supports GitHub, GitLab, and Azure DevOps.

Provider	Auth method	Notes
GitHub	OAuth authorization	Works with personal and organization repositories. Organization repositories may require admin approval.
GitLab	OAuth authorization	Supports gitlab.com and reachable self-managed GitLab instances.
Azure DevOps	Generic Git Connection using HTTPS and token	Connect with the repository HTTPS URL and a personal access token with repository permissions.

The generic Git Connection is useful beyond Azure DevOps. If your Git host supports HTTPS clone URLs and token authentication, you can usually connect it through this path.

Connect your Git provider

The setup flow is similar across providers:

1. Authorize Apidog or provide a token.
2. Select the repository.
3. Select the branch.
4. Configure sync or backup.

GitHub

For GitHub, authorize through GitHub OAuth.

Apidog requests repository access so it can read specs and push commits. If the repository belongs to a GitHub organization, an organization admin may need to approve third-party access before the repository appears in Apidog.

GitLab

For GitLab, authorize through GitLab OAuth.

Self-managed GitLab instances work if Apidog can reach the instance over the network.

Azure DevOps

For Azure DevOps, use the generic Git Connection.

You need:

• The repository HTTPS clone URL
• A personal access token, or PAT
• Read/write code permission for the target repository

Keep the PAT scoped as tightly as possible. Do not use a full-account token if a project-level or repository-level token is enough.

Permission checklist

Before connecting, verify the following:

• The repository is visible to the authorizing user.
• Organization-level third-party app approval is complete, if required.
• The token has read/write access to the target repository.
• The selected branch exists.
• Private repositories are accessible through the OAuth grant or token.

Once connected, bind your Apidog project to a repository and branch, usually main for the canonical spec. If you are still defining your Git process, read the guide on OpenAPI version control with Git.

Two-way sync with Spec-First Mode

Spec-First Mode turns Apidog into a Git-aware OpenAPI editor. You can read the full reference in the official Apidog documentation, but the implementation flow is straightforward.

Step 1: Edit the OpenAPI document

In Spec-First Mode, edit the OpenAPI document directly as YAML or JSON.

The editor provides:

• Syntax highlighting
• Live validation
• Auto-completion
• Parsed navigation for paths, operations, and schemas

Example OpenAPI path:

paths:
  /v1/orders/{orderId}:
    get:
      operationId: getOrder
      summary: Retrieve a single order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

Step 2: Commit the change

After editing, Apidog stages the spec change as a local edit.

Commit it with a clear message, for example:

Add GET /v1/orders/{orderId}

Step 3: Push to Git

Push the commit to the connected branch.

After the push succeeds, Apidog shows a sync indicator such as:

Synced just now

That confirms Apidog and the connected Git branch contain the same spec content.

Step 4: Pull repo changes back into Apidog

If a teammate edits the OpenAPI file in the repository, pull those changes into Apidog before making more edits.

This keeps Apidog aligned with the repository and prevents drift.

Step 5: Discard unwanted local edits

If you make experimental changes and decide not to keep them, discard unpushed edits. This reverts the working copy to the last synced state.

This workflow supports a Git-native API workflow: API spec changes move through the same review, history, and rollback process as application code.

Automatic Git backup of API specs

Automatic backup is simpler than sync. You configure it once, and Apidog pushes exported OpenAPI/Swagger files to Git on a schedule.

Use this when you want Git history and recovery without requiring everyone to edit specs through Git.

How backup works

1. Select a module in Apidog.
2. Configure the target Git repository.
3. Save the backup configuration.
4. Apidog exports the module’s OpenAPI/Swagger file.
5. Apidog pushes the file to the repository during a randomized off-peak nightly window.

GitHub, GitLab, and Azure DevOps are supported.

Each backup push creates a Git commit, so you can:

• Compare today’s API contract with a previous version
• See when a field, endpoint, or schema changed
• Restore a previous spec from Git if needed

Backup is one-way by design. Apidog writes to Git, but it does not pull repository changes back into Apidog. If you need repo-side edits to flow into Apidog, use Spec-First Mode instead.

Choose a branch and repository structure

Plan the Git structure before connecting the integration.

Branch strategy

For most teams:

• Use main for the canonical spec.
• Use feature branches for in-progress API changes.
• Open pull requests for review before merging into main.

Example workflow:

feature/add-orders-endpoint -> pull request -> main

Pointing Apidog directly at main is simpler, but it skips review unless your team has another approval process. Use direct main sync only for small teams or low-risk changes.

Repository strategy

You can use one repository per API or a monorepo.

Structure	Best for	Trade-off
One repo per API	Separate teams owning separate APIs	Cleaner access control and history
API spec monorepo	Platform teams managing many APIs	Easier central search and cross-API review

If you use a monorepo, give each module a predictable path:

api-specs/
  orders/
    openapi.yaml
  billing/
    openapi.yaml
  users/
    openapi.yaml

This keeps backups organized and makes pull request diffs easier to review.

Configure team permissions

Git integration depends on both Apidog permissions and Git provider permissions.

In Apidog

Limit sync and push permissions to people who own the API spec.

Recommended setup:

• API owners: can edit, commit, and push
• Developers and reviewers: can read and review
• Admins: can configure Git connections and permissions

This reduces accidental pushes from users who only need to inspect the API design.

In Git

For GitHub and GitLab, OAuth access follows the permissions of the authorizing user.

For Azure DevOps and generic Git connections, the PAT is the credential. Treat it like a secret:

• Do not paste it into shared docs.
• Scope it to the target repository or project.
• Rotate it regularly.
• Revoke it when the owner leaves the team.
• Replace expired or revoked tokens in Apidog.

The integration is only as secure as the credential behind it.

Handle merge conflicts and drift

Because Apidog writes real Git commits, normal Git conflict rules apply.

A conflict can happen when two people edit the same OpenAPI lines before syncing.

Example:

1. You edit the Order schema in Apidog.
2. A teammate edits the same schema in the repository.
3. Your teammate pushes first.
4. You try to sync.
5. Git detects overlapping YAML changes.

Resolve the conflict the same way you would resolve any Git conflict:

1. Pull the latest repository state.
2. Review the conflicting YAML.
3. Keep the correct fields, paths, or schema definitions.
4. Ensure the OpenAPI document is valid.
5. Commit and re-sync.

Apidog’s live validation helps catch malformed OpenAPI after conflict resolution.

To reduce conflicts:

• Pull before you edit.
• Pull before you push.
• Avoid multiple people editing the same schema at the same time.
• Use feature branches for larger API changes.

Drift is the slower version of the same problem. If the sync indicator does not show that the project is synced, reconcile before continuing.

Troubleshooting

Most issues come from authorization, branch selection, or pending sync state.

Symptom	Likely cause	Fix
Authorization fails or repository does not appear	Organization approval is missing, or token scope is insufficient	Ask an org admin to approve access. For Azure DevOps, create a PAT with read/write code scope.
Push is rejected	Token is revoked or expired, or user lacks write permission	Re-authorize the provider or update the PAT in Apidog.
Changes were pushed but are not visible	Wrong branch selected	Confirm the connected branch and switch it in project settings if needed.
Sync is stuck or “Synced just now” never appears	Local edits are unpushed, or remote changes need to be pulled	Commit and push local edits, or pull teammate changes first.
Merge conflict on the spec	Two users edited the same YAML lines	Resolve the YAML conflict, validate the OpenAPI document, and re-sync.
Backup did not run	Scheduled backup window has not occurred yet	Wait for the randomized nightly window or verify backup repository and branch settings.
You made edits you do not want to keep	Experimental local changes before commit	Discard unpushed edits to return to the last synced state.

If a problem appears suddenly, check credentials first. A revoked token, expired PAT, or missing organization approval explains many integration failures.

FAQ

Is Apidog Git sync one-way or two-way?

It depends on the workflow.

Spec-First Mode is two-way:

Apidog <-> Git

Automatic backup is one-way:

Apidog -> Git

Use Spec-First Mode when you want repository edits to come back into Apidog. Use backup when you only need scheduled exported specs in Git.

Where are my specs stored?

They are stored in the Git repository you connect.

For Spec-First Mode, the OpenAPI document lives on the branch you push to.

For automatic backup, each module’s exported OpenAPI/Swagger file is committed to the configured repository.

Which branch should I sync to?

Use main for the canonical API spec. Use feature branches for in-progress changes that need pull request review.

This mirrors the way most teams already ship code.

What happens if my token is revoked?

Pushes and backups that depend on that token fail because Apidog no longer has repository access.

Fix it by re-authorizing the provider or creating a new PAT for Azure DevOps and generic Git connections. After updating the credential in Apidog, sync and backup can resume.

Conclusion

Apidog Git integration gives you two practical ways to put API specs under version control:

• Use Spec-First Mode for two-way sync, commits, pull requests, and reviewable OpenAPI changes.
• Use automatic Git backup for scheduled one-way exports and versioned recovery points.

Both workflows support GitHub, GitLab, and Azure DevOps. Start by choosing the workflow, repository, branch, and permissions model. Then connect your provider and let your API specs live in the same Git process as the rest of your engineering work.