Gitlab Bot
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:
Name | Required | Description |
---|---|---|
CHECK_POLICY | Yes | Determines how the pipeline status should be handled if Spectral finds issues in a merge request. Options based on issue severity: "Fail on any issue" , "Fail on low and above" , "Fail on medium and above" , "Fail on high and above" , "Fail on critical only" , "Always Pass" |
GITLAB_SELF_HOSTED_DOMAIN | No | Provide the domain if you're running a self-hosted GitLab (e.g., https://my-gitlab-domain.com ). |
GITLAB_WEBHOOK_SECRET | No | A strong secret for securing the webhook (leave empty if using a vault). |
GITLAB_ACCESS_TOKEN | Yes, if not using vault | Generate it in your GitLab profile under Access Tokens, with the "api" scope (leave empty if using a vault). |
VAULT_KEY_GITLAB_ACCESS_TOKEN | No | The vault key to retrieve the GitLab access token (e.g., Spectral_GitlabBot_AccesToken ). Required if using a vault. |
VAULT_KEY_GITLAB_WEBHOOK_SECRET | No | The vault key to retrieve the GitLab webhook secret. Defaults to Spectral_GitlabBot_WebhookSecret . |
VAULT_KEY_SPECTRAL_DSN | No | The key in the vault where the Spectral DSN is stored. should be in the format of Spectral_Dsn |
GITLAB_SHOULD_SKIP_PIPELINE | No | Specifies whether to skip pipeline creation on push events. Options: true , false . Default: false . |
STRICT_MODE | No | If set to true , the check status is based on all issues found in the modified files, even if the issues are old. |
SPECTRAL_TAGS | No | Comma-separated list of tags to run Spectral with (e.g., base,iac,audit ). |
SPECTRAL_ENGINES | No | Comma-separated list of engines to run Spectral with (e.g., secrets,iac,oss ). Default: secrets . |
SPECTRAL_DSN | No | Your Spectral DSN from SpectralOps (leave empty if using a vault). |
SECRETS_VAULT | No | The vault where your secrets are stored. Currently supports aws_secrets_manager . |
CUSTOM_COMMENT | No | Custom text to add to the merge request summary (Markdown format). |
SHOULD_SKIP_INGEST | No | If set to true , findings won’t be sent to SpectralOps and won’t appear in your dashboard. Options: true , false . Default: false . |
S3_BLACK_LIST_BUCKET_NAME | No | Name of the S3 bucket containing the blacklist file. |
S3_BLACK_LIST_OBJECT_KEY | No | The S3 object key for the blacklist file. |
CUSTOM_SSL_CERTIFICATE | No | The SSL certificate content for on-prem GitLab. Use this variable if not using AWS Secrets Manager for the certificate. |
VAULT_KEY_CUSTOM_SSL_CERTIFICATE | No | The vault key to retrieve the custom SSL certificate. Defaults to Spectral_custom_ssl_certificate . |
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
(forGITLAB_ACCESS_TOKEN
)Spectral_GitlabBot_WebhookSecret
(forGITLAB_WEBHOOK_SECRET
)Spectral_Dsn
(forSPECTRAL_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
Terraform
Deploy AWS resources using our Terraform module (set the integration_type
parameter to gitlab
).
Setup GitLab Webhooks
After deploying the bot, configure the webhook URL at the project or system level in GitLab:
Project-Level Webhook
- Go to
Settings -> Webhooks
in your project. - Add a new webhook.
- Enter the webhook URL, which may vary with each deployment.
- Under
Triggers
, selectPush events
andMerge request events
. - (Optional) If using multiple webhooks with the same Spectral bot instance, configure the custom header
X-Spectral-App-Id
.
System-Level Webhook
- Go to
Admin Area -> System Hooks
in your GitLab instance. - Add a new webhook.
- Enter the webhook URL, which may vary with each deployment.
- Under
Triggers
, selectPush events
andMerge 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
- In CloudWatch, click
Create Alarm
, thenSelect Metric
. - Choose the
Errors
metric for the Lambda and clickSelect Metric
. - Set the statistic to
Sum
and select your preferred period for threshold measurement. - Under conditions, set a
Static
threshold, selectGreater
, and set the threshold value to at least 1. ClickNext
. - Add email recipients for the alarm notifications. Click
Next
, name the alarm, and clickNext
again. - 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
-
Download and Unzip Lambda Code:
- Download the Lambda code as a
.zip
file. - Unzip the file.
- Download the Lambda code as a
-
Add
multi_app.json
:- Place the
multi_app.json
file in the unzipped directory.
- Place the
-
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 themulti_app.json
file is included.
Configuring the gitlab
Object in multi_app.json
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 theX-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 toCHECK_POLICY
.spectral_dsn
: Use a different DSN for this GitLab app. Defaults toSPECTRAL_DSN
.webhook_secret
: Custom webhook secret for this GitLab app. Defaults toGITLAB_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
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.
Updated 15 days ago