How Do You Sync an OpenAPI Spec to GitHub Two Ways?

If your OpenAPI document lives in Git but you edit it inside an API client, the usual workflow is fragile: copy YAML out, paste it back, check whether someone else changed the file, and hope the import/export step did not lose anything. A Git-backed OpenAPI workflow removes that manual sync work.

Try Apidog today

This guide shows how to sync an OpenAPI spec to GitHub with Apidog’s Spec-First Mode. You will connect a Git provider, create a project from a repository, edit the OpenAPI YAML, commit the change, and push it back to GitHub. The same workflow also applies to GitLab.

What two-way sync means

Two-way sync means the OpenAPI file moves in both directions without a manual export/import step:

• Apidog to Git: edit the OpenAPI document in Apidog, then commit and push it to the selected branch.
• Git to Apidog: when someone pushes changes to that branch from an IDE or another Git client, Apidog pulls the updated spec back into the editor.

The repository remains the source of truth. Apidog becomes an editor on top of the Git-tracked spec.

That is the idea behind a Git-native API workflow: the spec is versioned, reviewed, and tracked like any other file in your codebase.

Prerequisites

Before starting, make sure you have:

• Apidog installed or available through the web app.
• An Apidog account.
• A GitHub or GitLab repository containing an OpenAPI document.
• Write access to the branch you want to sync.
• Spec-First Mode enabled.

Azure DevOps is also supported through Git Connection.

If you only have read access, Apidog can pull the spec, but it cannot push commits back to the repository.

Step 1: Connect your Git provider

Authorize Apidog to access your Git provider.

1. Open Apidog.
2. Create a new project.
3. Select Spec-First Mode.
4. Choose your provider: GitHub or GitLab.
5. Click Authorize.
6. Complete the OAuth flow in your browser.
7. Grant access to the repositories you want Apidog to sync.

On GitHub, you can usually scope access to specific repositories instead of granting access to the entire account.

After authorization, Apidog returns you to the project setup flow. You only need to connect each provider once; future projects can reuse the connection.

For the full reference, including Azure DevOps through Git Connection, see the Spec-First Mode documentation.

Step 2: Create a project from a repository and branch

Next, point Apidog at the OpenAPI document in your repository.

1. Select the repository that contains your OpenAPI file.
2. Choose the branch to sync against, such as main.
3. Confirm the OpenAPI file path if prompted, for example:
   • openapi.yaml
   • docs/openapi.yaml
   • spec/openapi.json
4. Create the project.

Apidog loads the spec from the selected branch and parses it into a navigable API outline. Endpoints, schemas, and other OpenAPI objects appear in the sidebar.

At this point, you are editing the repository-backed spec, not a separate imported copy.

Step 3: Edit the OpenAPI YAML

Spec-First Mode gives you a code editor for the raw OpenAPI document, with syntax highlighting, inline validation, and auto-completion.

For example, add a simple health check endpoint:

paths:
  /health:
    get:
      summary: Service health check
      operationId: getHealth
      responses:
        '200':
          description: Service is up
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

As you edit:

• The sidebar updates as Apidog parses the document.
• New operations appear in the endpoint tree.
• YAML syntax issues are flagged inline.
• Invalid OpenAPI structures, missing fields, bad $ref values, or indentation errors can be caught before committing.

This makes the workflow closer to editing code in an IDE while still keeping the API spec visible as an API project.

For more on Git history, diffs, and spec changes, see OpenAPI version control with Git.

Step 4: Commit and push the change

When the spec update is ready, commit it from Apidog.

1. Open the Git or source-control panel.
2. Review the modified OpenAPI file.
3. Write a commit message, for example:

Add /health endpoint

1. Click Commit & Push.

Apidog creates a normal Git commit on the selected branch and pushes it to the remote repository.

You can then open GitHub and verify that:

• The commit appears in the branch history.
• The OpenAPI file contains the change.
• The commit touches the expected file.

If you change your mind before pushing, discard the unpushed edits. Until you commit and push, the changes stay local to Apidog.

Step 5: Verify sync status

Use the sync indicator to confirm whether Apidog and the remote branch are aligned.

After a successful push, the indicator shows a synced state such as:

Synced just now

As time passes, the status updates. If someone else pushes changes to the same branch, Apidog pulls those changes into the editor.

If the indicator shows a pending, outdated, or diverged state, treat that as a signal to pull, review, or resolve conflicts before continuing.

Troubleshooting

Authorization fails or pushes are rejected

If Apidog cannot push to the repository, check whether:

• The OAuth token expired.
• Access was revoked in GitHub or GitLab.
• The repository permissions changed.
• You authorized the wrong account.

Re-run the provider authorization flow if needed.

You selected the wrong branch

If commits are not appearing where expected, confirm the branch selected during project setup.

Also check branch protection rules. If main requires pull requests, direct pushes may be rejected. In that case, sync against a writable branch or adjust the repository workflow.

Merge conflicts appear

Conflicts can happen if another developer changes the same part of the OpenAPI file while you are editing.

Resolve it like any other Git conflict:

1. Pull the latest remote changes.
2. Review the overlapping YAML changes.
3. Keep the correct version or combine both edits.
4. Validate the OpenAPI document.
5. Commit and push again.

Because the spec is plain text, conflict resolution works the same way it does for code.

Validation errors show up in the editor

Fix validation errors before committing whenever possible.

Common issues include:

• Bad YAML indentation.
• Missing responses.
• Invalid $ref paths.
• Incorrect schema nesting.
• Duplicate operation IDs.

A valid spec keeps generated docs, mocks, and tests consistent.

FAQ

Does this work with GitLab and Azure DevOps?

Yes. Spec-First Mode supports GitHub and GitLab directly. Azure DevOps is supported through Git Connection.

The workflow is the same:

1. Connect provider.
2. Select repository and branch.
3. Edit the spec.
4. Commit and push.

Only the authorization flow differs by provider.

What happens if someone edits the spec while I am working in Apidog?

Apidog pulls remote changes back into the editor as part of two-way sync.

If the changes are in different parts of the file, they can merge cleanly. If both edits touch the same lines, you resolve a standard Git conflict.

Can I undo a change before it reaches GitHub?

Yes. Until you click Commit & Push, your edits are local.

Use discard for unpushed edits to return the OpenAPI document to the last synced state.