Gitlab Bot

Monitor, alert, and discover sensitive data in your code for each merge request. Get instant feedback on any change you make in a merge request. Spectral Bot can be installed directly on organizations, user accounts, groups and grant access to specific Projects.

Integration Environment Variables

SELF_HOSTED_GITLAB_DOMAINNoif you're running a self-hosted Gitlab provide the domain here. eg.
STRICT_MODENoIf set to true, check status is based on all issues found in the modified files (even if the issues are old)
SPECTRAL_TAGSNoTags list to run Spectral with, separated by commas (eg base,iac,audit).
SPECTRAL_ENGINESNoEngines list to run Spectral with, separated by commas (eg secrets,iac,oss). Default is 'secrets'
SPECTRAL_DSNNoYour Spectral DSN retrieved from SpectralOps (leave blank if you are using vault)
GITLAB_WEBHOOK_SECRETNoAny strong secret would be fine (leave blank if you are using vault)
GITLAB_TOKENNoGenerate it in your Gitlab profile -> Access Tokens, check the "api" scope (leave blank if you are using vault)
SECRETS_VAULTNoThe vault you're storing your secrets in. Currently only supports aws_secrets_manager

Using vault

Instead of storing your secrets directly on the configuration of your Lambda, it is recommended for you to use a vault instead.

In order to use a vault, it is needed to set another environment variable called SECRETS_VAULT which contains the type of the vault you are using.

Available values:

  • AWS secrets manager - aws_secrets_manager

Currently, we are supporting AWS secret manager, but in the future we are planning to support more vaults.

In your vault, make sure you set the following 3 secrets in your vault:

  • Spectral_GitlabBot_GitlabToken (for GITLAB_TOKEN)
  • Spectral_GitlabBot_WebhookSecret (for GITLAB_WEBHOOK_SECRET)
  • Spectral_Dsn (for SPECTRAL_DSN)

AWS Secrets Manager

If you are deploying using CloudFormation or Terraform, notice that the role created for the lambdas would give permission to perform secretsmanager:GetSecretValue action only for those 3 secrets.

Deploy the Bot

Deploy using one of the following methods:

Cloud Formation

Launch stack


Deploy AWS resources using our Terraform module (set the integration_type param value to gitlab).


Go to our DockerHub repo for the Gitlab scanner and follow instructions.

Setup Gitlab Project Webhooks

Setup Gitlab webhooks by running the create_webhooks executable. Download it for Mac (digest), Linux (digest) or Windows (digest) and use it:


This will setup webhooks for the projects under the group GROUP_ID (recursively). Look at ./create_webhooks -h for usage.


It is highly recommended monitoring the bot errors. It can be done easily if the bot is hosted using AWS lambda through CloudWatch alarms.

To create an alarm do the following:

  1. In Cloudwatch, click on Create Alarm, and then Select Metric.
  2. Select the Errors metric for the lambda and click on Select Metric.
  3. Set the statistic to be Sum and select the required period for the threshold measuring.
  4. Under conditions, choose static threshold, choose Greater, and set the threshold value to at least 1. Click Next.
  5. Insert to Emails be to be alarmed. Click Next, name the alarm and click Next again.
  6. Go over the summary, and if everything makes sense to you - click OK.

That's it 💪

Now merge requests for all the projects you selected are protected by Spectral. Any issues found will be written as a note on the MR.