***

title: Integrate Postman with GitLab CI/CD
updated: 2024-10-04T00:00:00.000Z
slug: docs/integrations/available-integrations/ci-integrations/gitlab-ci
max-toc-depth: 2
----------------

<Info class="iconless-callout">
  **[GitLab Self-managed integrations are available with Postman Enterprise plans with the API Builder add-on.](https://www.postman.com/pricing/)**
</Info>

[GitLab CI/CD](https://docs.gitlab.com/ee/ci/) is a continuous integration and continuous delivery (CI/CD) service that's integrated with GitLab SaaS and GitLab Self-managed. Software development teams can use GitLab CI/CD to automatically build, test, and deploy code in GitLab.

To set up a GitLab CI/CD integration for your API in the Postman API Builder, first create a pipeline in GitLab and then configure your API in Postman. After you set up the integration, you can view the status of builds or start a new build, all from within Postman.

## Create a pipeline in GitLab

If you haven't already, create a pipeline in the GitLab repository you use for your API. To create a pipeline, add a `.gitlab-ci.yml` file in the root of your repository. You define your pipeline in this YAML file. To learn more, see [the GitLab CI/CD documentation](https://docs.gitlab.com/ee/ci/).

## Configure a GitLab CI/CD integration

To configure a GitLab CI/CD integration for GitLab SaaS or GitLab Self-managed, do the following:

1. Open your API by selecting **APIs** in the sidebar. *Each API can be linked to one CI project*.

   <Info class="iconless-callout">
     **Tip:** If you've already authenticated with GitLab to connect a Git repo for source control, you can use the same authentication. To automatically create the integration, under **Test and Automation**, click **Connect to GitLab**.
   </Info>

2. Click **Test and Automation**.

3. Under **Automate**, select **GitLab SaaS** or **GitLab Self-managed**.

4. You'll be prompted to authorize Postman to access your GitLab account. After you grant access, you can close the browser tab and return to Postman.

To continue configuring a GitLab CI/CD integration for GitLab SaaS, do the following:

1. Enter a **Nickname** to help you recognize the integration later. Postman pre-fills a nickname in the format `GitLab-{API_NAME}`, and you can edit it if you want.
2. Select the GitLab **Workspace** with your API repository.
3. Select the **CI project** used for your API.
4. Click **Connect**.

<img alt="Connect to GitLab CI/CD" src="https://assets.postman.com/postman-docs/v10/gitlab-saas-connect-ci-cd-v10.jpg" />

To continue configuring a GitLab CI/CD integration for GitLab Self-managed, do the following:

{/* vale Vale.Terms = NO */}

{/* vale Vale.Spelling = NO */}

1. Enter the URL of your GitLab Self-managed domain.
2. Enter your GitLab personal access token. When [creating your token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html), make sure to select the **api**, **read\_api**, **read\_user**, and **write\_repository** scopes.
3. Click **Authenticate**.

{/* vale Vale.Terms = YES */}

{/* vale Vale.Spelling = YES */}

<img alt="Connect to GitLab CI/CD" src="https://assets.postman.com/postman-docs/gitlab-hosted-connect-ci-cd-v9-19.jpg" />

## View build status

After you set up a GitLab integration, information for build jobs is available in Postman. For each build you can view the branch, start time, and status (`Successful` or `Failed`). You can also view the results of collection runs that are [configured in your pipeline using the Postman CLI](#view-collection-run-details).

To view build jobs, open an API and click **Test and Automation**. The most recent jobs are listed under the repository name.

Click **View All Builds** to view the full list of build jobs. From here you can take the following actions:

* Use the dropdown lists to filter jobs by branch or build status.
* To open a build in GitLab, select the build name.
* To start a new build, click **Run Build**. Select or enter the name of the branch to use, and then click **Run Build**. To cancel a running build, click **Cancel** next to the build.
* To get the latest build status information, click <img alt="Refresh icon" src="https://assets.postman.com/postman-docs/aether-icons/action-refresh-stroke.svg#icon" width="16px" /> **Refresh**.
* To edit or delete the integration, click <img alt="Options icon" src="https://assets.postman.com/postman-docs/aether-icons/action-options-stroke.svg#icon" width="16px" /> **View more actions**.

<img alt="View all GitLab builds" src="https://assets.postman.com/postman-docs/v10/collection-runs-v10-2.jpg" />

## View collection run details

Using the Postman CLI, you can run Postman collections with your API tests as part of a GitLab pipeline. The Postman cloud reporter can send details about the collection runs back to Postman.

To view details for collections that were run as part of a build, first [configure the Postman CLI for GitLab](#configure-the-postman-cli-for-gitlab-cicd) and then [start a new build](#view-build-status). After the build is complete, use the arrows to expand a build and expand a collection to view details about a collection run.

<Info class="iconless-callout">
  Click **View Report** to view a collection run report in the Postman **History**. Learn more about using the [Collection Runner](/docs/collections/running-collections/intro-to-collection-runs/).
</Info>

{/* vale postman-style-guide.Headings = NO */}

## View API Governance and API Security rule violations

{/* vale postman-style-guide.Headings = YES */}

{/* vale Vale.Terms = NO */}

Using the Postman CLI, you can enforce [Postman API Governance and API Security rules each time the pipeline runs](/docs/api-governance/api-definition/api-definition-warnings/#track-governance-and-security-rule-violations-in-cicd) using the [api lint](/docs/postman-cli/postman-cli-options/#governance-and-security) command ([Enterprise teams only](https://www.postman.com/pricing/)).

{/* vale Vale.Terms = YES */}

To view the results of API Governance and API Security checks that ran as part of the build, first [configure the Postman CLI for GitLab](#configure-the-postman-cli-for-gitlab-cicd). Next, [start a new build](#view-build-status). After the build completes, use the arrows to expand a build and expand an API specification stored in the Postman API Builder to view any rule violations.

<img alt="View API Governance and API Security results" src="https://assets.postman.com/postman-docs/v10/api-governance-and-security-results-v10.jpg" />

## Configure the Postman CLI for GitLab CI/CD

With the help of the Postman CLI and the Postman API, you can run Postman collections with your API tests as part of your GitLab pipeline. First generate the Postman CLI configuration code in Postman. Then add the configuration code to the `.gitlab-ci.yml` file in your GitLab repository.

Each time the pipeline runs, the Postman CLI runs the collections that contain your tests. You can view the results of your tests in Postman. You can also enforce [API Governance and API Security rules](/docs/api-governance/api-definition/api-definition-warnings/#track-governance-and-security-rule-violations-in-cicd) each time the pipeline runs ([Enterprise teams only](https://www.postman.com/pricing/)).

<Info class="iconless-callout">
  Before you begin, make sure you've already [set up an integration](#configure-a-gitlab-cicd-integration) between your API and GitLab CI/CD.
</Info>

To generate configuration code for the Postman CLI, do the following:

1. Open your API and click **Test and Automation**.
2. Under the repository name, click **View All Builds**.
3. Click **Configure Postman CLI**.
4. Select a **Collection** to run during pipeline builds. To be available in the dropdown list, you must first [add the collection as a test suite](/docs/design-apis/api-builder/testing-an-api/#adding-api-tests) to your API in the Postman API Builder. You can also select an **Environment** to use.
5. (Optional) Select the checkbox to enforce API Governance and API Security rules each time the CI/CD pipeline runs ([Enterprise teams only](https://www.postman.com/pricing/)).
6. Select the **Operating system** for your CI/CD pipeline.
7. Click **Copy Postman CLI Command** to copy the Postman CLI configuration.

   <img alt="Generate the Postman CLI configuration" src="https://assets.postman.com/postman-docs/v10/generate-postman-cli-v10-3.jpg" />

To add the Postman CLI configuration to your GitLab pipeline, do the following:

1. Edit the `.gitlab-ci.yml` file at the root of your GitLab repository.
2. Add the Postman CLI configuration you copied from Postman to the `.gitlab-ci.yml` file. Then, replace all instances of `$POSTMAN_API_KEY` with a valid [Postman API Key](/docs/developer/postman-api/authentication/#generate-a-postman-api-key).
3. Commit and push the changes to your remote repository. This will automatically start a build in GitLab.
4. To view the test results in Postman, open your API and click **Test and Automation**. Learn more about [Viewing collection run details](#view-collection-run-details).