Skip to navigation
ObservePostman API CatalogConnect to your services

Discover APIs and services through code connection

View as Markdown

The API Catalog can connect your Git repository to a Postman workspace. The API Catalog supports the following Git providers:

  • GitHub
  • GitLab
  • Bitbucket

Alternatively, if you already have Git-connected Postman workspaces, the API Catalog can automatically show all APIs in those workspaces.

Select your connection

To select your connection, do the following:

  1. From Home icon Home, click API Catalog.
  2. Click Service discovery.
  3. Click Add icon Add New Sources.
  4. If you haven’t connected your Git repository yet, under Code Discovery, click Configure on your Git provider. If you have already connected your Git repository, under Manual Import, click Postman Workspace.

If you haven’t connected your Git repository, follow the steps for your Git provider:

Connect GitHub

To connect a GitHub repository, you need push permissions on the repository. The Repository list only shows repositories that are accessible, and that you have push permissions on.

To connect GitHub, do the following:

  1. On the Configure GitHub Integration page, under Choose GitHub Repository, select an Organization.

    If you don’t see your organization, click install the Postman App and install it on your personal account or organization. Then return to the page and select your organization.

  2. Select a Repository.

  3. Under Select a Postman Workspace, select the workspace you want to connect. To find a workspace, enter its name in the search box.

    If you don’t see the workspace you want, do the following to create one:

    1. Under Teams, select the team that will own the new workspace.
    2. Click Create new workspace.

  4. Click Start setup.

Postman opens the service page in the API Catalog and creates a pull request in your GitHub repository. The Integrate Postman Collections and Environments from File System pull request merges the feature/postman-integration branch into your default branch and adds the following:

  • postman/ — The exported contents of the linked Postman workspace, such as collections and environments.
  • .postman/config.json — Links your repository to the Postman workspace.
  • .github/workflows/postman-publish.yml — A GitHub Actions workflow that keeps the repository files in sync with Postman Cloud. The workflow installs the Postman CLI, logs in with your Postman API key, and runs postman workspace push.

Before you merge the pull request, the repository owner must add the POSTMAN_API_KEY secret to the repository:

  1. In GitHub, go to Settings > Secrets and variables > Actions.
  2. Click New repository secret.
  3. For Name, enter POSTMAN_API_KEY. For Secret, enter your Postman API key. To generate a key, go to Settings > API Keys in Postman. For more information, see Generate a Postman API key.
  4. Click Add secret.

The workflow fails if POSTMAN_API_KEY isn’t configured. After you add the secret, click Merge pull request, then check the Actions tab to verify that the Publish changes to Postman workflow runs successfully. For more information about the workflow, see Automate Native Git with CI/CD.

Connect GitLab

To connect a GitLab repository, you need Developer access or higher on the GitLab project. The project list only shows projects where you have this level of access.

To connect GitLab, do the following:

  1. On the Configure GitLab Integration page, under Choose GitLab Project, select a Group/namespace.

  2. Select a Project.

  3. Under Select a Postman Workspace, select the workspace you want to connect. To find a workspace, enter its name in the search box.

    If you don’t see the workspace you want, click Create new workspace. Postman creates a workspace with the same name as the discovered service.

  4. Click Start setup.

Postman opens the service page in the API Catalog and creates a merge request in your GitLab project. To finish connecting the repository, do the following in GitLab:

  1. Add POSTMAN_API_KEY as a masked CI/CD variable. If the pipeline runs on a protected branch or tag, also mark the variable as protected. For more information, see Generate a Postman API key.
  2. Open the Integrate Postman Collections and Environments from File System merge request and click Merge.
  3. Verify that the postman-publish.yaml pipeline runs successfully.

The merge request adds a .postman/config.json file that links your repository to the Postman workspace. If GitLab shows a Verify your identity to run this pipeline message, click Verify identity so the pipeline can run.

Connect Bitbucket

To connect Bitbucket, you need admin permissions on the repository so you can enable Pipelines and add repository variables.

To connect Bitbucket, do the following:

  1. On the Configure Bitbucket Integration page, if Postman shows “Failed to load Bitbucket workspaces. Please re-authenticate.”, click Reconnect Bitbucket and authorize Postman in Bitbucket.

  2. Under Choose Bitbucket Repository, select a Bitbucket workspace. The Repository list shows all repositories in that workspace.

  3. Select a Repository.

  4. Under Select a Postman Workspace, select the workspace you want to connect. To find a workspace, enter its name in the search box, or click Load more workspaces.

    If you don’t see the workspace you want, click Create new workspace.

  5. Click Start setup.

  6. When Postman shows Integration complete!, click Done.

Postman opens the service page in the API Catalog and creates a pull request in your Bitbucket repository. The Integrate Postman Collections and Environments from File System pull request adds the following:

  • postman/ — The exported contents of the linked Postman workspace, such as collections and environments.
  • .postman/config.json — The workspace configuration required for synchronization.
  • bitbucket-pipelines.yml — A Bitbucket pipeline that keeps the repository files in sync with Postman Cloud.

Before you merge the pull request, the repository owner must do the following in Bitbucket:

  1. Go to Repository Settings > Pipelines > Settings and turn on Enable Pipelines. Pipelines are off by default, and committing the pipeline file doesn’t turn them on.
  2. Go to Repository Settings > Pipelines > Repository variables and add a POSTMAN_API_KEY variable. Select Secured so the value doesn’t appear in pipeline logs. To generate a key, go to Settings > API Keys in Postman. For more information, see Generate a Postman API key.

The pipeline fails if POSTMAN_API_KEY isn’t configured. After you complete these steps, click Merge on the pull request.

View your service

Once connected, the API Catalog will automatically discover your APIs and add them to the catalog. You can manage your APIs in the catalog and set rules for them as needed.

After setup, the new service appears under Integrated services. A new service shows NO SPEC in the Development environment until you link a spec. The first scan can take a few minutes. When it finishes, Critical Insights shows any findings, such as missing Postman Insights, test automation, or CI/CD runs. Click Re-scan to scan again.