GitHub Enterprise Server, GitLab Self-Managed, and Azure DevOps Server (hosted on-premises) integrations are available with Postman Enterprise plans with the API Builder add-on.

You can connect your API to an on-premises Git repository to sync your API definition and collections between Postman and the repository. Postman supports connecting to GitHub Enterprise Server, GitLab Self-Managed, or Azure DevOps Server repositories.

After connecting, you can push and pull changes between Postman and branches in the remote repository. When it’s time to release, you can publish an API version to make your changes available to consumers.

The steps below are for connecting to the on-premises versions of GitHub Enterprise Server, GitLab Self-Managed, and Azure DevOps Server. If you need to connect to a cloud-hosted repository, go toConnect to a cloud-hosted Git repository.

Using an on-premises repository overview

If you are on aPostman Enterprise plan with the API Builder add-on, you can connect an API in Postman to your on-premises Git repository. This enables you to sync changes between the repository and Postman.

To connect toGitHub Enterprise Server or GitLab Self-Managed, create a new installed app in Postman. To connect toAzure DevOps server, use a personal access token.

Keep in mind the following when connecting to an on-premises repository:

• You must be on aPostman Enterprise plan with the API Builder add-on to connect to a repository hosted on-premises. If you’re not on a Postman Enterprise plan with the API Builder add-on, you won’t be able to connect to GitHub Enterprise Server, GitLab Self-Managed, or Azure DevOps Server. You can stillconnect to a cloud-hosted repository.

• You must use thePostman desktop app to connect to GitHub Enterprise Server, GitLab Self-Managed, or Azure DevOps Server. You can’t use thePostman web app to connect to an on-premises GitHub repository.

• All communication is between the Postman desktop app on your computer and the on-premises repository. Your computer must be able to access the repository. No Git requests go through Postman’s cloud servers. The Postman desktop app connects directly to your Git server, and you don’t need to allow any Postman IP addresses for your repository. The repository will show the IP address of your computer as the source for all Git requests.

• You can connect one or more APIs to a remote repository. You can keep your APIs separate in the repository using files or branches. Learn more aboutconnecting more than one API to the same repository.

Connecting to GitHub Enterprise Server or GitLab Self-Managed

To connect to a repository hosted in GitHub Enterprise Server or GitLab Self-Managed,create an installed app in Postman. To complete this process, you’ll also need to create an OAuth app in GitHub Enterprise Server or GitLab Self-Managed. You need to complete this process once for a domain URL. After you create the installed app, anyone on the team can use it toconnect to repositories using the same domain URL.

Creating an installed app

Installed apps streamline the process of adding integrations by enabling all members of a team to use the same stored authorization details. To create an installed app, you must have theTeam Admin role.

To create an installed app for GitHub Enterprise Server or GitLab Self-Managed, do the following:

1. In Postman, openTeam Settings by selectingTeam > Team Settings.

2. ClickInstalled apps.

3. Select the repository provider you want to add an installed app for (GitHub Enterprise Server orGitLab Self-Managed).

4. Enter aName to help you recognize the installed app later.

5. Enter the domain URL of your repository. Format the domain URL as follows:

   • GitHub Enterprise Server - Use the base URL of your Git server, for example:https://my-github-server.example.com
   • GitLab Self-Managed - Use the base URL of your Git server, for example:https://gitlab.example.com

6. Create an OAuth app by following the instructions for your Git provider (GitHub Enterprise Server orGitLab Self-Managed). Use the following values:

   • Homepage URL - Enter the Postman homepage URL:https://www.postman.com
   • Authorization callback URL orRedirect URI - Enter the authorization callback URL provided in Postman:https://integration-oauth.pstmn.io/v1/api-git-callback.html
   • Scopes - Make sure to select the appropriate scopes when creating the OAuth app to enable Postman to read and write to your repository. For GitHub, select therepo anduser scopes. For GitLab Self-Managed, select theapi scope.

7. After registering the OAuth app, copy the app’sClient ID andClient secret and enter them in Postman.

8. ClickSave to finish creating the installed app.

Connecting an API using an installed app

After youcreate an installed app, any API editor on the team can use it to connect an API to GitHub Enterprise Server or GitLab Self-Managed.

To connect an API using an installed app, do the following:

1. ClickAPIs in the sidebar and select an API.

2. UnderConnect repository, clickConnect and selectGitHub Enterprise Server orGitLab Self-Managed.

3. Select the authorized domain of your repository and clickAuthenticate.

   

4. A browser tab opens asking you to sign in to your repository. Follow the onscreen instructions. When you’re finished, close the browser tab and return to Postman.

5. For GitHub, enter theOrganization and theRepository where the API will be stored. For GitLab, enter theGroup andProject for your API.

6. Select theInitial branch for the API. Any changes you make in Postman are stored in the initial active branch. (You can switch to another branch to make it the active branch at any time.)

7. Select anAPI schema file to add to your API. If you’re working on amulti-file API definition, make sure to select theroot definition file in your repository. The root file is the base file that has references to other files in the API definition. If you leave this field blank, no definition files are added to your API. You canmanually add a definition file from your repository later.

8. Select aCollection directory where the collections linked to your API will be stored in the repository. If you leave this field blank, apostman/collections directory will be created in the root of the repository.

9. ClickConnect Repository.

   The root definition file you selected is added to your API. For OpenAPI 2.0 and 3.0 APIs, Postman scans for any dependent files referenced in the root definition file and automatically adds them to your API. You can alsomanually add more definition files from your repository as needed.

Connecting to Azure DevOps Server

To connect an API to a repository hosted in Azure DevOps Server, use a personal access token.

1. ClickAPIs in the sidebar and select an API.

2. UnderConnect repository, clickConnect and selectAzure DevOps Server.

3. Enter theDomain URL of your repository. You can enter a new domain or select a domain you’ve used before from the list. Use the name and port of your Git server along with the collection, for example:https://my-azure-server:8080/my-collection

4. Enter aPersonal access token to access the repository. Ensure that the token has the required permissions as specified on theConnect your repository page.

5. ClickNext.

   

6. Enter theOrganization and theRepository where the API will be stored.

7. Select theInitial branch for the API. Any changes you make in Postman are stored in the initial active branch. (You can switch to another branch to make it the active branch at any time.)

8. Select anAPI schema file to add to your API. If you’re working on amulti-file API definition, make sure to select theroot definition file in your repository. The root file is the base file that has references to other files in the API definition. If you leave this field blank, no definition files are added to your API. You canmanually add a definition file from your repository later.

9. Select aCollection directory where the collections linked to your API will be stored in the repository. If you leave this field blank, apostman/collections directory will be created in the root of the repository.

10. ClickConnect Repository.

    The root definition file you selected is added to your API. For OpenAPI 2.0 and 3.0 APIs, Postman scans for any dependent files referenced in the root definition file and automatically adds them to your API. You can alsomanually add more definition files from your repository as needed.

Postman stores your authorized accounts so you can use them to connect to other repositories and services. Learn more aboutmanaging connected accounts for remote repositories.

Disconnecting an on-premises repository

After you disconnect a remote repository, you can no longer sync changes between Postman and the repository.

1. ClickAPIs in the sidebar and select an API.
2. ClickSource Control in the right sidebar.
3. In theSource Control pane, click and selectDisconnect repository.
4. Enter the name of the API to confirm, then clickDisconnect.

Next steps

After you’ve connected a remote repository to your API, you can:

• Work with branches, push and pull changes, and resolve conflicts. Learn more aboutmanaging changes using Git.
• Publish an API version to a workspace or your team’s Private API Network. Learn more aboutpublishing an API version.

• On this page

• Using an on-premises repository overview
• Connecting to GitHub Enterprise Server or GitLab Self-Managed
• Connecting to Azure DevOps Server
• Disconnecting an on-premises repository
• Next steps