How Do You Connect Apidog to GitHub, GitLab ?

If your API specs live in Apidog but your source of truth lives in Git, you want the two to agree. Apidog Git integration closes that gap. It lets you connect a GitHub, GitLab, or Azure DevOps repository to your project, push your OpenAPI specs into version control, and pull repo changes back into Apidog. You get a clean audit trail, code-review on spec changes, and a backup that survives anything that happens inside the app.

This is the broad reference. It covers every provider Apidog supports, both ways the product talks to Git, and the practical decisions you’ll face: which repo, which branch, who can push, and what to do when something breaks. If you only need the focused GitHub walkthrough, read the dedicated guide on how to sync your OpenAPI spec to GitHub. Here, we go wider.

What Apidog Git integration does

Apidog talks to Git in two distinct ways. They solve different problems, and you can use one, the other, or both. Mixing them up is the most common source of confusion, so let’s separate them first.

The first capability is two-way sync through Spec-First Mode. You edit your OpenAPI document as YAML or JSON inside Apidog’s IDE-style editor, commit your changes, and push them to the connected branch. When someone else updates the spec in the repo, you pull those changes back into Apidog. This is a real round trip: edits flow out to Git, and repo changes flow back in.

The second capability is automatic Git backup of API specs. Here, Apidog exports each module’s OpenAPI/Swagger file and pushes it to a repository on a schedule. This is one-directional and hands-off. You configure it once, and the system keeps a versioned copy of your specs in Git without you lifting a finger. It’s a safety net, not an editing workflow.

Keep this distinction in mind for the rest of the article. When we say “sync,” we mean the two-way Spec-First Mode flow. When we say “backup,” we mean the scheduled, one-directional export.

Supported Git providers

Apidog supports the three providers most teams already use. GitHub and GitLab connect directly through their native authorization flows. Azure DevOps connects through a generic Git Connection, which works with any Git host that speaks standard HTTPS auth.

The generic Git Connection is the escape hatch. If your host isn’t GitHub or GitLab by name, but it speaks standard Git over HTTPS with token auth, the generic connection usually handles it. Azure DevOps is the headline case, but the same path covers self-hosted setups that expose an HTTPS clone URL.

Connecting your Git provider

The connection step is where you grant Apidog the access it needs to read and write your repo. The mechanics differ slightly per provider, but the shape is the same: authorize, pick a repo, pick a branch.

For GitHub, you authorize through GitHub’s OAuth screen. Apidog requests repository access so it can read the spec and push commits. If the repo belongs to an organization, GitHub may route the request through an organization admin who approves third-party access. Personal repos authorize immediately under your own account.

For GitLab, the flow mirrors GitHub. You log in through GitLab’s OAuth screen and grant repository access. Self-managed GitLab works as long as Apidog can reach the instance over the network.

For Azure DevOps, you use the generic Git Connection. Instead of an OAuth handshake, you supply the repository’s HTTPS clone URL and a personal access token (PAT). Create the PAT in Azure DevOps with permission to read and write code, then paste it into Apidog. The token is the credential that lets Apidog push commits, so scope it to exactly the repos it needs.

A few permission notes that save time:

• Org vs personal repos. Organization repositories often require an admin to approve the integration once. If your authorization seems to succeed but Apidog can’t see the repo, an admin approval is usually missing.
• Scope the token tightly. For Azure DevOps and any generic connection, grant the PAT read/write on code for the target project only. Avoid full-account tokens.
• Private repos are fine. Apidog works with private repositories. The access comes from the authorization or token you provide, not from public visibility.

Once the provider is connected, you create the Apidog project from a repository plus a branch, typically main. That pairing is what binds your specs to a specific place in version control. If you’re new to the broader practice, our guide on OpenAPI version control with Git covers the conventions worth adopting before you wire everything up.

Two-way sync with Spec-First Mode

Spec-First Mode is where the two-way sync lives. It turns Apidog into a spec editor that commits to Git like any other code. You can read the full has reference in the official Apidog documentation; here’s how the round trip works in practice.

You edit the OpenAPI document directly as YAML or JSON. The editor is IDE-style: it gives you syntax highlighting, live validation, and auto-completion, so a malformed $ref or a missing required field surfaces while you type rather than after you push. As you edit, the left sidebar auto-parses the document into an outline, paths, operations, and schemas, so you can navigate a large spec without scrolling through raw text.

A typical edit looks like this. Say you add an endpoint:

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'

When you save that change, Apidog stages it as a local edit. You then commit with a message and push to the connected branch, exactly as you would with any Git workflow. After the push lands, a sync indicator reads “Synced just now” your confirmation that Apidog and the branch hold the same content.

The pull direction is just as important. When a teammate edits the spec in the repo and pushes, you pull those changes into Apidog to bring your local copy up to date. This is what makes the integration genuinely two-way: the repo isn’t just a backup target, it’s a peer.

If you make edits you don’t want to keep, you can discard unpushed edits before committing. That reverts your working copy to match the last synced state, which is handy when you’re experimenting and decide the change isn’t worth keeping.

This commit-and-push rhythm is the heart of a Git-native API workflow spec changes go through the same review, history, and rollback machinery as the rest of your codebase. Reviewers comment on the YAML diff in a pull request, approvals gate the merge, and your API design history reads like your code history.

Automatic Git backup of API specs

The backup capability is the quieter half of Apidog Git integration, and it asks almost nothing of you after setup. You point a module at a repository, and Apidog handles the rest.

Here’s the mechanism. Apidog can back up the OpenAPI/Swagger file for each module to a Git repository, GitHub, GitLab, and Azure DevOps are all supported. Once you save the backup configuration, the system automatically pushes the module’s OpenAPI Spec file to the specified repo. The push happens during a randomized off-peak window at night, which keeps it out of your working hours and spreads load.

What gets stored is the exported OpenAPI/Swagger document for that module, a snapshot of the API contract as it stands. Because each push is a commit, you accumulate a version history in Git. You can diff last week’s contract against today’s, see exactly when a field changed, and restore a prior version straight from the repo if you ever need to.

The backup flow is one-directional by design. Apidog writes to the repo; it doesn’t read changes back from it. If you want repo edits to flow into Apidog, that’s Spec-First Mode’s job, not backup’s. Use backup when your goal is durability and history without altering how your team works day to day.

Choosing a branch and repo structure

The structural decisions you make up front shape how smooth the integration feels later. Two questions dominate: which branch, and how many repos.

Branch choice. Most teams sync to main for the canonical spec and use has branches for in-progress design. Pointing Apidog at a has branch lets you iterate on a spec change in isolation, open a pull request, and merge once review passes, your API design follows the same branching model as your code. Pointing Apidog at main directly is simpler but skips the review gate, so reserve it for small teams or low-risk changes.

One repo or many. There’s no single right answer, but the trade-offs are clear:

• One repo per API keeps each spec’s history clean and its access controls narrow. It’s the natural fit when different teams own different APIs.
• A monorepo for all specs centralizes everything and simplifies cross-API search and review. It works well when one platform team owns the API surface. Just keep the directory layout predictable, one folder per module, so backups and syncs don’t collide.

If you run a monorepo, give each module its own path. That keeps the automatic backups tidy and makes spec diffs easy to read in review.

Team permissions and access

Git integration touches credentials, so it’s worth being deliberate about who can do what. Permissions live in two places: inside Apidog, and inside your Git provider.

Inside Apidog, team permissions are configured during project setup. That’s where you decide who can sync and push to the connected repo. Limit push rights to the people who own the spec, and let everyone else read. This prevents accidental pushes from contributors who are just browsing the API design.

Inside your Git provider, the credential matters. For GitHub and GitLab, the OAuth authorization carries the access of the user who granted it. For Azure DevOps and generic connections, the personal access token is the credential, treat it like a secret. Don’t paste tokens into shared docs, scope them to the target repos only, and rotate them on the same cadence you rotate other secrets. If someone leaves the team, revoke their token and re-authorize under an account that’s still active.

The principle is simple: the integration is only as locked-down as the weakest token behind it. Keep scopes narrow and ownership clear.

Handling merge conflicts and drift

Because Apidog commits real Git history, it inherits Git’s conflict model, and Git’s tools for resolving it. Conflicts happen when two people change the same part of the spec before syncing.

Picture the scenario. You edit the Order schema in Apidog and push. A teammate edited the same schema on the repo side and pushed first. When you try to reconcile, Git flags a conflict on the YAML, because both sides changed overlapping lines. This isn’t an Apidog problem; it’s a normal Git merge conflict on a YAML file, and you resolve it the normal way.

To stay out of conflicts, pull before you push. Bringing the latest repo state into Apidog before committing your own changes keeps your working copy current and shrinks the window where two edits collide. When a conflict does land, resolve it on the YAML the same way you’d resolve any merge conflict: pick the correct lines, keep the document valid, and re-sync. The editor’s live validation helps here, a botched merge that breaks the OpenAPI structure shows up immediately rather than after you push.

Drift, where Apidog and the repo quietly diverge, is the slow version of the same problem. The “Synced just now” indicator is your early warning. If it doesn’t show synced, something is unpushed or unpulled. Treat that as a prompt to reconcile before the gap widens.

Troubleshooting

Most integration issues trace back to auth, branch selection, or an interrupted sync. Work through the table before assuming something deeper is wrong.

If authorization is the recurring theme, and it usually is, start by confirming the credential is alive and scoped correctly. A revoked token or a missing org approval explains the majority of “it just stopped working” reports.

FAQ

Is the sync one-way or two-way?

It depends on which capability you’re using. Spec-First Mode is two-way: you push edits to Git and pull repo changes back into Apidog. The automatic backup is one-way: Apidog exports each module’s spec to the repo on a schedule and doesn’t read changes back.

Where are my specs stored?

In the Git repository you connect. For Spec-First Mode, your OpenAPI document lives on the branch you push to. For automatic backup, each module’s exported OpenAPI/Swagger file is committed to the repo you configured. In both cases, Git holds the versioned copy, and you keep full control of the repository.

Which branch should I sync to?

Use main for the canonical spec and has branches for in-progress changes. Syncing to a has branch lets a spec change go through a pull request and review before it merges, which mirrors how your code already moves through Git.

What happens if my token is revoked?

Pushes start failing because Apidog no longer has write access. Re-authorize the provider, or, for Azure DevOps and generic connections, generate a new personal access token and update it in Apidog. Once the credential is restored, sync and backup resume normally.

Conclusion

Apidog Git integration gives you two complementary tools: two-way sync through Spec-First Mode for teams who treat the spec as code, and automatic per-module backup for anyone who just wants a versioned safety net. Both work across GitHub, GitLab, and Azure DevOps, so you connect the provider you already use rather than adopting a new one.

Pick the capability that matches your goal. If you want review and history on every spec change, set up Spec-First Mode and adopt the commit-and-push rhythm. If you want durability without changing your workflow, turn on backup and let the nightly push handle it. Many teams run both. When you’re ready to wire it up, connect your provider, point a project at a repo and branch, and let your API specs live where the rest of your work already does.