## GitLab CI/CD Pipelines

GitLab CI/CD pipelines are a part of GitLab’s integrated continuous integration and deployment features. They allow you to define and automate the different stages and tasks in your software development workflow. This document provides an overview and example job to integrate Endor Labs into your GitLab CI pipeline.

## High Level Usage Steps

1. Setup authentication to Endor Labs
2. Install your build toolchain
3. Build your code
4. Scan with Endor Labs

### Authentication to Endor Labs

Endor Labs recommends using keyless authentication in continuous integration environments. Keyless Authentication is more secure and reduces the cost of secret rotation. To set up keyless authentication see [the keyless authentication documentation](https://docs.endorlabs.com/setup-deployment/ci-cd/keyless-authentication). If you choose not to use keyless authentication you can configure an API key and secret in GitLab for authentication using the following steps. See [managing API keys for more information](https://docs.endorlabs.com/platform-administration/api-keys).

### Configure API key and secret in GitLab

1. In your GitLab environment, select the project you want to scan.
2. Go to **Settings** > **CI/CD**.
3. Click **Expand** in the Variables section.
4. Click the **Add variable** button at the bottom of the section.
5. In the **Key** field, enter **ENDOR_API_CREDENTIALS_SECRET**.
6. In the **Value** field, enter your Endor Labs API secret.
7. Under **Flags**, make sure you select **Mask variable**.
8. Repeat the previous steps to add your API key as the variable **ENDOR_API_CREDENTIALS_KEY**.

### Configure your GitLab CI pipeline

**Important**: GitLab CI/CD pipelines check out commits in a detached HEAD state, which can lead to fragmented branch tracking in Endor Labs. See [Set up branch tracking in GitLab](https://docs.endorlabs.com/setup-deployment/ci-cd/scan-with-gitlab#set-up-branch-tracking-in-gitlab) to configure proper branch context.

1. Create a `.gitlab-ci.yml` file in the root directory of your project if you do not already have one.
2. In your `.gitlab-ci.yml` file customize the job configuration based on your project’s requirements using the example below.
3. Modify the image field to align with the build tools necessary for building your software packages.
4. Update the before_script section to include any additional steps required before executing the scan, such as installing dependencies or building your project.
5. Save and commit the `.gitlab-ci.yml` file to your GitLab repository.
6. GitLab will automatically detect the `.gitlab-ci.yml` file and trigger the defined job whenever there are changes pushed to the repository.
7. Monitor the progress and results of the CI pipeline in the GitLab CI/CD interface.

You can use the following example job to get started. Make sure to customize this job with your specific build environment and build steps.

```yaml
# You can copy and paste this template into a new `.gitlab-ci.yml` file.
# You should not add this template to an existing `.gitlab-ci.yml` file by using the `include:` keyword.

stages:
  - Scan
Endor Labs Dependency Scan:
  stage: test
  image: node # Modify this image to align with the build tools necessary for building your software packages
  dependencies: []
  variables:
    ENDOR_ENABLED: "true"
    ENDOR_ALLOW_FAILURE: "false"
    ENDOR_NAMESPACE: "example" # Replace with your Endor Labs namespace
    ENDOR_PROJECT_DIR: "."
    ENDOR_ARGS: |
      --path=${ENDOR_PROJECT_DIR}
      --detached-ref-name=$CI_COMMIT_REF_NAME
      --output-type=summary
      --exit-on-policy-warning
      --dependencies --secrets --git-logs
  before_script:
    - npm install yarn # Replace with the build steps for your Endor Labs job.
  script:
    - curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o ./endorctl;
    - echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64)  ./endorctl" | sha256sum -c;
    - chmod +x ./endorctl
    - ./endorctl scan ${ENDOR_ARGS}
  rules:
    - if: $ENDOR_ENABLED != "true"
      when: never
    - if: $ENDOR_ALLOW_FAILURE == "true"
      allow_failure: true
    - if: $ENDOR_ALLOW_FAILURE != "true"
      allow_failure: false
```

If you use Endor Labs with an EU tenant, use `https://api.eu.endorlabs.com` instead of `https://api.endorlabs.com`.

## SAST scans in GitLab

You can run SAST scans in your GitLab CI pipeline to identify security vulnerabilities and code quality issues in your source code. SAST scanning analyzes your source code for potential security weaknesses based on enabled rules and generates findings based on your configured finding policies.

### SAST scan

To run a SAST scan, add `--sast` to your `ENDOR_ARGS` variable.

```yaml
variables:
  ENDOR_ARGS: |
    --path=${ENDOR_PROJECT_DIR}
    --sast
    --dependencies --secrets

script:
  - ./endorctl scan ${ENDOR_ARGS}
```

### AI SAST detection agent scan

To run an AI SAST detection agent scan, add `--ai-sast` to your `ENDOR_ARGS` variable. The AI SAST detection agent identifies security vulnerabilities beyond traditional rule-based SAST detection.

```yaml
variables:
  ENDOR_ARGS: |
    --path=${ENDOR_PROJECT_DIR}
    --ai-sast
    --dependencies --secrets

script:
  - ./endorctl scan ${ENDOR_ARGS}
```

### AI SAST MR scan

To run an AI SAST MR scan, add `--ai-sast`, `--pr`, `--pr-incremental`, and `--pr-baseline` to your `ENDOR_ARGS` variable. The scan analyzes only the code changed by the merge request and surfaces the net new findings introduced by the change. A baseline AI SAST scan must exist on the target branch first. See [AI SAST PR scans](https://docs.endorlabs.com/scan/ai-sast/ai-sast-pr-scans) to learn more.

```yaml
variables:
  ENDOR_ARGS: |
    --path=${ENDOR_PROJECT_DIR}
    --ai-sast
    --pr
    --pr-incremental
    --pr-baseline=main

script:
  - ./endorctl scan ${ENDOR_ARGS}
```

## Set up branch tracking in GitLab

In Git, a detached HEAD state occurs when the repository checks out a specific commit instead of a branch reference. In this state, Git points the HEAD directly to a commit hash, without associating it with a named branch. Proper branch context enables Endor Labs to:

- Associate scans with the correct branch
- Identify scans on the monitored default branch
- Track findings and display metrics accurately across branches

Without proper branch configuration, Endor Labs may create multiple branch entries for the same logical branch, leading to fragmented reporting and inaccurate metrics.

```yaml
variables:
  ENDOR_ARGS: |
    --path=${ENDOR_PROJECT_DIR}
    --detached-ref-name=$CI_COMMIT_REF_NAME
    --dependencies --secrets

script:
  - ./endorctl scan ${ENDOR_ARGS}
```

## Run MR scans

MR scans are point-in-time scans that run on merge requests to detect new policy violations and security issues introduced by the changes. Unlike default branch scans which create monitored versions, MR scans compare findings against the baseline to surface only new issues. To run scans on merge requests, use the `--pr` flag. This flag tells endorctl to treat the scan as a merge request scan and compare findings against the target branch baseline.

```yaml
Endor Labs MR Scan:
  stage: test
  image: node
  variables:
    ENDOR_NAMESPACE: "example" # Replace with your Endor Labs namespace
    ENDOR_PROJECT_DIR: "."
    ENDOR_ARGS: |
      --path=${ENDOR_PROJECT_DIR}
      --detached-ref-name=$CI_COMMIT_REF_NAME
      --pr
      --dependencies --secrets
  before_script:
    - npm install # Replace with your build steps
  script:
    - curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o ./endorctl
    - chmod +x ./endorctl
    - ./endorctl scan ${ENDOR_ARGS}
  rules:
    - if: $CI_MERGE_REQUEST_IID
```

## Enable MR comments

You can enable MR comments in your GitLab CI pipeline to automatically post comments on merge requests when policy violations are detected. MR comments build on top of [MR scans](https://docs.endorlabs.com/setup-deployment/ci-cd/scan-with-gitlab#run-mr-scans) by posting the scan results directly on the merge request.

**Configure a GitLab token**: Configure a GitLab CI/CD variable following the same steps as described in [Configure API key and secret in GitLab](https://docs.endorlabs.com/setup-deployment/ci-cd/scan-with-gitlab#configure-api-key-and-secret-in-gitlab). Add a variable with the key `ENDOR_SCAN_SCM_TOKEN` and set its value to your GitLab personal access token with the `api` scope. Make sure to select **Mask variable** under Flags.

### Configure the pipeline for MR comments

The following example configuration enables MR comments in your GitLab CI pipeline:

```yaml
Endor Labs MR Scan:
  stage: test
  image: node
  variables:
    ENDOR_NAMESPACE: "example" # Replace with your Endor Labs namespace
    ENDOR_PROJECT_DIR: "."
    ENDOR_ARGS: |
      --path=${ENDOR_PROJECT_DIR}
      --detached-ref-name=$CI_COMMIT_REF_NAME
      --pr
      --enable-pr-comments
      --scm-pr-id=$CI_MERGE_REQUEST_IID
      --scm-token=$ENDOR_SCAN_SCM_TOKEN
      --dependencies --secrets
  before_script:
    - npm install # Replace with your build steps
  script:
    - curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o ./endorctl
    - chmod +x ./endorctl
    - ./endorctl scan ${ENDOR_ARGS}
  rules:
    - if: $CI_MERGE_REQUEST_IID
```

### Configure an action policy

After you enable MR comments, you need to set up an action policy to allow comments to be posted on merge requests. See [Configure Action policy for PR comments](https://docs.endorlabs.com/scan/pr-scans/pr-comments#configure-action-policy-for-pr-comments) for more information.