Monitor, alert, and detect sensitive data in your code for each push or merge request. Get instant feedback on any changes you make in a merge request. The Spectral Bot can be installed directly on organizations, user accounts, groups, and specific projects. It supports both system-level webhooks (GitLab Enterprise) and group-level webhooks.

Integration Environment Variables

To configure the Spectral Bot, set the following environment variables:

Using a Vault

Instead of storing your secrets directly in the Lambda configuration, it's recommended to use a vault. To do so, set the SECRETS_VAULT environment variable to specify the type of vault you're using.

Supported Vaults

• AWS Secrets Manager: aws_secrets_manager

In your vault, set the following secrets:

• Spectral_GitlabBot_AccesToken (for GITLAB_ACCESS_TOKEN)
• Spectral_GitlabBot_WebhookSecret (for GITLAB_WEBHOOK_SECRET)
• Spectral_Dsn (for SPECTRAL_DSN)

For AWS Secrets Manager, if deploying with CloudFormation or Terraform, ensure the Lambda role has permission to access these secrets using the secretsmanager:GetSecretValue action.

Deploy the Bot

Choose one of the following deployment methods:

CloudFormation

Launch Stack

Terraform

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

Docker

Follow the deployment instructions in our DockerHub repo.

Setup GitLab Webhooks

After deploying the bot, configure the webhook URL at the project or system level in GitLab:

Project-Level Webhook

1. Go to Settings -> Webhooks in your project.
2. Add a new webhook.
3. Enter the webhook URL, which may vary with each deployment.
4. Under Triggers, select Push events and Merge request events.
5. (Optional) If using multiple webhooks with the same Spectral bot instance, configure the custom header X-Spectral-App-Id.

System-Level Webhook

1. Go to Admin Area -> System Hooks in your GitLab instance.
2. Add a new webhook.
3. Enter the webhook URL, which may vary with each deployment.
4. Under Triggers, select Push events and Merge request events.

Monitoring

It's highly recommended to monitor the bot for errors. If hosted on AWS Lambda, you can easily do this using CloudWatch Alarms.

Creating a CloudWatch Alarm

1. In CloudWatch, click Create Alarm, then Select Metric.
2. Choose the Errors metric for the Lambda and click Select Metric.
3. Set the statistic to Sum and select your preferred period for threshold measurement.
4. Under conditions, set a Static threshold, select Greater, and set the threshold value to at least 1. Click Next.
5. Add email recipients for the alarm notifications. Click Next, name the alarm, and click Next again.
6. Review the summary, and if everything is correct, click OK.

Advanced

Configuring Multiple GitLab Apps with a Single Instance

You can configure multiple GitLab apps with a single instance of the Spectral Bot by setting up the multi_app.json file in the root directory. This is only supported for multiple group webhooks and not system-level webhooks.

Steps for AWS Lambda Deployment

1. Download and Unzip Lambda Code:

   • Download the Lambda code as a .zip file.
   • Unzip the file.

2. Add multi_app.json:

   • Place the multi_app.json file in the unzipped directory.

3. Re-zip and Upload:

   • Select all the files in the unzipped directory.
   • Zip the files again.
   • Upload the new .zip file to AWS Lambda, ensuring the multi_app.json file is included.

Configuring the gitlab Object in multi_app.json

The gitlab object in multi_app.json is a dictionary containing all GitLab apps. For each app, set the access_token in the code or use a vault.

• <app_id>: A unique string ID for each app, matching the value of the X-Spectral-App-Id custom header in your group webhook.

Optional Parameters

In addition to access_token, you can configure the following:

• check_failure_policy: Custom failure policy for scans from this GitLab app. Defaults to CHECK_POLICY.
• spectral_dsn: Use a different DSN for this GitLab app. Defaults to SPECTRAL_DSN.
• webhook_secret: Custom webhook secret for this GitLab app. Defaults to GITLAB_WEBHOOK_SECRET.
• secret_vault: Store secrets (webhook secret, app private key, spectral DSN) in a vault at the app level.

Example multi_app.json Configuration

{
  "gitlab": {
    "<app_id>": {
      "access_token": "",
      "spectral_dsn": "",
      "webhook_secret": "",
      "secret_vault": {
        "name": "aws_secrets_manager",
        "key_webhook_secret": "",
        "key_access_token": "",
        "key_spectral_dsn": ""
      }
    }
  }
}

Custom SSL Certificate Support

To support self-signed SSL certificates for on-prem GitLab, create a new AWS secret named Spectral_custom_ssl_certificate containing the certificate content. Alternatively, you can use the environment variable CUSTOM_SSL_CERTIFICATE to define the certificate.

If you prefer to use AWS Secrets Manager with a custom key instead of the default (Spectral_custom_ssl_certificate), set the VAULT_KEY_CUSTOM_SSL_CERTIFICATE environment variable to the desired key.

Note: Do not set both VAULT_KEY_CUSTOM_SSL_CERTIFICATE and CUSTOM_SSL_CERTIFICATE at the same time, as the CUSTOM_SSL_CERTIFICATE environment variable will take precedence.

That's it 💪

Now, your selected projects' merge requests are protected by Spectral. Any issues found will be noted directly on the MR.