Connect your API to an on-premises Git repository

GitHub Enterprise Server, GitLab Self-Managed, and Azure DevOps Server (hosted on-premises) integrations are available on 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 to Using a cloud-hosted Git repository.

Using an on-premises repository overview

If you are on a Postman 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 to GitHub Enterprise Server or GitLab Self-Managed, create a new installed app in Postman. To connect to Azure DevOps server, use a personal access token.

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

• You must be on a Postman 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 still connect to a cloud-hosted repository.

• You must use the Postman desktop app to connect to GitHub Enterprise Server, GitLab Self-Managed, or Azure DevOps Server. You can't use the Postman 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 about connecting 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 to connect 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 the Team Admin role.

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

1. In Postman, open Team Settings by selecting Team > Team Settings.

2. Select Installed apps.

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

4. Enter a Name 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 or GitLab Self-Managed). Use the following values:

   • Homepage URL - Enter the Postman homepage URL: https://www.postman.com
   • Authorization callback URL or Redirect 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 the repo and user scopes. For GitLab Self-Managed, select the api scope.

7. After registering the OAuth app, copy the app's Client ID and Client secret and enter them in Postman.

8. Select Save to finish creating the installed app.

Connecting an API using an installed app

After you create 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. Select APIs in the sidebar and select an API.

2. Under Connect repository, select Connect and select GitHub Enterprise Server or GitLab Self-Managed.

3. Select the authorized domain of your repository and select Authenticate.

   

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 the Organization and the Repository where the API will be stored. For GitLab, enter the Group and Project for your API.

6. Select the Initial 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 an API schema file to add to your API. If you're working on a multi-file API definition, make sure to select the root 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 can manually add a definition file from your repository later.

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

9. Select Connect 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 also manually 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. Select APIs in the sidebar and select an API.

2. Under Connect repository, select Connect and select Azure DevOps Server.

3. Enter the Domain 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 a Personal access token to access the repository. Ensure that the token has the required permissions as specified on the Connect your repository page.

5. Select Next.

   

6. Enter the Organization and the Repository where the API will be stored.

7. Select the Initial 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 an API schema file to add to your API. If you're working on a multi-file API definition, make sure to select the root 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 can manually add a definition file from your repository later.

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

10. Select Connect 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 also manually 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 about managing 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. Select APIs in the sidebar and select an API.
2. Select the source control icon in the right sidebar.
3. In the Source Control pane, select the more actions icon and select Disconnect repository from Postman.
4. Enter the name of the API to confirm, then select Disconnect.

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 about managing changes using Git.
• Publish an API version to a workspace or your team's Private API Network. Learn more about publishing an API version.