Bitbucket Pre-Receive Hook

A Bitbucket pre-receive hook prevents software developers from pushing commits to Gitlab if Code Security found security issues in the code. This feature is supported only for a Gitlab instance on a Linux server.

Prerequisites

  • The Gitlab instance must be installed on a Linux server.

  • Code Security must be installed on the same Linux server as the Gitlab instance. See Getting Started with Code Security.

  • To load a custom Code Security configuration from the repository, you must have a Bitbucket service account with read-only personal access. If you do not have this type of Bitbucket service account, custom configurations from the repository do not apply.

Step 1: In Code Security, configure environment variables

Configure the Bitbucket pre-receive hook in Code Security by defining environment variables.

Environment variable

Description

Example value

SPECTRAL_BIN

Path to the Code Security binary.

$HOME/.spectral/spectral

SPECTRAL_DSN

DSN from Code Security (SpectralOps), in Settings > Organization.

https://spu-xxxx@get.spectralops.io

SPECTRAL_COMMAND

Code Security command line arguments.

scan --include-tags base,iac

BITBUCKET_SERVER_BASE_URL

The URL of the Bitbucket server.

https://mydomain.com/bitbucket

BITBUCKET_PAT

The personal access token for Bitbucket (optional functionality to load spectral.yaml from repo).

TmljZSB0cnkhIEJ1dCB0aGlzIGlzbid0IGEgcmVhbCBvbmUu

SPECTRAL_CHECK_POLICY

The severity of findings allowed before the push is rejected.

These values are supported:

  • fail on any issue (default value)

  • fail on low and above

  • fail on medium and above

  • fail on high and above

  • fail on critical

  • always pass

fail on any issue

SPECTRAL_CUSTOM_REJECT_MESSAGE

A custom text to append to the rejection message.

Spectral has rejected your push

Example configuration

Copy 
SPECTRAL_DSN="https://spu-xxxx@get.spectralops.io"
SPECTRAL_CHECK_POLICY="fail on high and above"
BITBUCKET_SERVER_BASE_URL="https://mydomain.com/bitbucket"
BITBUCKET_PAT="TmljZSB0cnkhIEJ1dCB0aGlzIGlzbid0IGEgcmVhbCBvbmUu"
SPECTRAL_COMMAND="scan --include-tags base,iac"
SPECTRAL_BIN="~/.spectral/spectral"

Step 2: On the Bitbucket server, install the pre-receive hook

  1. Download the Code Security plugin JAR file to your computer.

  2. In the Bitbucket server UI, open the Administration settings.

  3. Click Manage apps > Upload app.

  4. Upload the Spectral plugin JAR file to the Bitbucket server.

  5. Do one of these:

    • Enable the hook for the entire Bitbucket server:

      1. by going to the project -> Project settings -> Hooks and enabling "Spectral Pre Receive Hook"

    • You can also enable the hook for specific repository by going to the specific repository -> Repository settings -> Hooks and enabling "Spectral Pre Receive Hook"