---
title: "GitLab"
description: "Learn how to set up StackHawk security testing in your GitLab CI/CD pipeline for automated application security scanning and vulnerability management."
url: https://docs.stackhawk.com/integrations/ci-cd/gitlab/
---

# GitLab

![GitLab](https://docs.stackhawk.com/images/integrations/logos/gitlab.svg)

You can run HawkScan in your GitLab pipeline to automate scanning on code check-in. This can be a great addition to an existing pipeline, typically as a step that occurs after deploying your app to an integration environment where HawkScan can reach it.

Since HawkScan 6.0.0, the `hawk` CLI is a self-contained native binary, so our example below installs it with the hawk CLI [install script](https://docs.stackhawk.com/stackhawk-cli/#install-with-a-script), with no Docker required. If you’d rather run HawkScan as a Docker container, see the [Docker Alternative](#docker-alternative).

## Secure Your API Key

HawkScan will need your StackHawk API key to submit scan results to the platform. Save your key as a set of masked and protected environment variables in your GitLab project. You will use them to pass your API key to HawkScan. From GitLab Project View, click on **Settings**, then **CI/CD** in the left pane to create them.

Our API keys contain an ID component, and a secret component. They take the form:

```shell
hawk.<HAWK_API_ID>.<HAWK_API_SECRET>
```

GitLab can only mask variable values with [Base64 characters](https://base64.guru/learn/base64-characters), which does not include the `.` character. So you will need to break down your StackHawk API key into its component parts, *ID* and *secret*.

For example, if your API key is:

```shell
hawk.AAaaAAaaAAaaAAaaAAaa.BBbbBBbbBBbbBBbbBBbb
```

You should create two variables,

```shell
HAWK_API_ID=AAaaAAaaAAaaAAaaAAaa
HAWK_API_SECRET=BBbbBBbbBBbbBBbbBBbb
```

Mark these variables Protected and Masked in the web console, like so:

![Masked Variables](https://docs.stackhawk.com/images/integrations/cicd/gitlab/cicd-gitlab-variables.png)

## Configure Your GitLab Job

At the base directory of your code repository, add a `.gitlab-ci.yml` pipeline configuration file. Configure it to install and run the `hawk` CLI:

```yaml title=".gitlab-ci.yml"
hawkscan:
  image: ubuntu:22.04
  # Optional: pin a version (6.0.0 or later). Leave it unset to install the latest release.
  # variables:
  #   HAWK_INSTALL_VERSION: "6.6.0"
  before_script:
    - apt-get update -qq && apt-get install -qq -y curl
    - curl -fsSL https://download.stackhawk.com/hawk/install.sh | sh
    - export PATH="$HOME/.hawk/bin:$PATH"
  script:
    - hawk --api-key="hawk.${HAWK_API_ID}.${HAWK_API_SECRET}" scan
```

In this configuration, `before_script` installs `curl`, runs the install script, and adds the install directory, `~/.hawk/bin`, to the PATH. The script installs the latest HawkScan release and checks its checksum; to run the same version every time, set `HAWK_INSTALL_VERSION` in the job’s `variables`. The script doesn’t change the PATH itself, so keep the `export PATH` line. GitLab runs `before_script` and `script` in the same shell, so the `hawkscan` job’s `script` can then run the scan. The StackHawk API key is injected from the secure environment variables, `HAWK_API_ID` and `HAWK_API_SECRET`. Your pipeline may have other jobs, for instance to build and deploy your application before scanning it.

### Docker Alternative

If you’d rather run HawkScan as a Docker container, you will need to enable Docker commands in your pipeline, as described in GitLab’s documentation [here](https://docs.gitlab.com/ee/ci/docker/using_docker_build):

```yaml title=".gitlab-ci.yml"
image: docker:19.03.1
services:
  - docker:19.03.1-dind
before_script:
  - docker pull stackhawk/hawkscan
hawkscan:
  script:
    - |
      docker run -v $(pwd):/hawk:rw -t \
        -e API_KEY="hawk.${HAWK_API_ID}.${HAWK_API_SECRET}" \
        -e NO_COLOR=true \
        stackhawk/hawkscan
```

#### Docker Configuration Prerequisites

In order to load the scanner’s configuration files, the `[runners.docker]` section in `config.toml` needs to be configured to:

1. Run in privileged mode (`privileged = true`)
2. Contain `docker.sock` and `/builds` mappings in the `volumes` list in `config.toml`

For example:

```yaml
[[runners]]
  name = "stackhawk-test"
  url = "https://git.example.org/"
  token = "xxxxxxxxxxxxxxxxxxxx"
  executor = "docker"
    [runners.docker]
      tls_verify = false
      image = "docker:stable"
      privileged = true
      disable_cache = false
      volumes = ["/var/run/docker.sock:/var/run/docker.sock","/cache","/builds:/builds"]
      shm_size = 0
```

## Configure HawkScan

Now create a `stackhawk.yml` file at the base of your code repository. For our example, we target our `Development` environment API endpoint, `http://example.com`.

```yaml title="stackhawk.yml"
app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  host: http://example.com
  env: Development

hawk:
  startupTimeoutMinutes: 1
  spider:
    base: false
```

Replace the `host` entry with your test endpoint, and update `applicationId` with your App ID from StackHawk.

The `hawk.spider.base: false` element tells HawkScan to limit its scope to a single endpoint, `/`. That helps keep the scan time short while you work on integrating it into your pipeline. You can expand the scope later.

## Run It

Check those two files, `.gitlab-ci.yml` and `stackhawk.yml`, into source control, and head over to the GitLab app console to watch your job run. And once the job is complete, check your account at StackHawk to check your scan details!

## Troubleshooting

See the [Help Center](https://help.stackhawk.com/en/) for troubleshooting information around running HawkScan with GitLab and other CI/CD solutions.