Connect your API to a cloud-hosted Git repository

You can connect your API to a cloud-hosted Git repository to sync your API definition and collections between Postman and the repository. Postman supports connecting to GitHub, Bitbucket, GitLab SaaS, or Azure DevOps 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 cloud-hosted versions of GitHub, Bitbucket, GitLab SaaS, or Azure DevOps. If you need to connect to an on-premises repository, go to Using an on-premises Git repository.

Using a cloud-hosted repository overview

You can connect an API in Postman to your cloud-hosted Git repository. This enables you to sync changes between the repository and Postman.

Keep in mind the following when connecting to a cloud-hosted Git repository:

  • The user account used for authentication requires full access to repositories. To contribute to the API, each user must authenticate with their own account.

  • For GitHub connections, there's a limit of ten auth tokens per user per application imposed by GitHub. If you create more than ten connections with the same user, tokens beyond this limit will be revoked in the order that they were created. Teams can use other Postman accounts to create more than ten integration.

  • For Azure DevOps connections, make sure to enable third-party application access for your organization. If you don't enable third-party access, Postman won't be able to connect to your repository. In Azure DevOps, go to your organization settings, select Policies, and turn on the toggle next to Third-party application access via OAuth.

  • 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 a cloud-hosted repository

You can connect your API to a GitHub, Bitbucket, GitLab SaaS, or Azure DevOps repository hosted in the cloud.

  1. Select APIs in the sidebar and select an API.

  2. Under Connect repository, select Connect and select the type of repository you want to connect to (GitHub, Bitbucket, GitLab SaaS, or Azure DevOps).

    If you want to connect to GitHub Enterprise Server, GitLab Self-Managed, or Azure DevOps Server, see Using an on-premises repository.

  3. 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.

  4. On the Connect your repository page, enter the Organization or Workspace and the Repository where the API will be stored. (For GitLab, enter the Group and Project for your API.)

  5. 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.)

  6. 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.

  7. 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.

  8. 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.

Connecting to a cloud-hosted repo

Managing connected accounts for remote repositories

After you connect an API to a remote repository, other editors of the API must authenticate to be able to contribute to the API. Postman will prompt editors to authenticate the next time they open the API.

Postman stores the accounts you've authorized with. After connecting to one repository, you can connect to other repositories that use the same Git provider without having to re-authenticate.

To manage services you've authorized with, select the settings icon Settings icon in the header, select Settings, and select the Connected accounts tab. Learn more about managing connected accounts.

Disconnecting a cloud-hosted 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 Git branch icon in the right sidebar.
  3. In the Source Control pane, select the more actions icon 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:

Last modified: 2023/09/15