Bitbucket pre receive hook

Bitbucket pre-receive repository hook

The hook prevents pushing commits with issues that Spectral found. It can be enabled at the project or repository level.


  • Bitbucket server on Linux (Windows not supported)
  • Spectral must be installed on the server: Instructions
  • Bitbucket service account with read-only personal access token (optional)
    This is required to load custom .spectral/ configuration from the repository. If not set, custom configuration from the repository will not apply.


All configuration is done through environment variables.

Environment variableDescriptionExample value
SPECTRAL_BINPath to the Spectral binary$HOME/.spectral/spectral
SPECTRAL_DSNDSN from SpectralOps, under Settings > Organizationhttps://[email protected]
SPECTRAL_COMMANDSpectral command line argumentsscan --include-tags base,iac
BITBUCKET_SERVER_BASE_URLThe URL to the Bitbucket server
BITBUCKET_PATThe personal access token for Bitbucket (optional, to load spectral.yaml from repo)TmljZSB0cnkhIEJ1dCB0aGlzIGlzbid0IGEgcmVhbCBvbmUu
SPECTRAL_CHECK_POLICYThe severity of findings allowed before the push is on any issue
SPECTRAL_CUSTOM_REJECT_MESSAGEA custom text to append to the rejection messageSpectral has rejected your push

SPECTRAL_CHECK_POLICY supports the following values:

  • fail on any issue (default)
  • fail on low and above
  • fail on medium and above
  • fail on high and above
  • fail on critical
  • always pass

Example configuration

SPECTRAL_DSN="https://[email protected]"
SPECTRAL_CHECK_POLICY="fail on high and above"
SPECTRAL_COMMAND="scan --include-tags base,iac"

Installation on Bitbucket server

  • Download the Spectral plugin JAR file.
  • Open your Bitbucket server UI -> Administration settings
  • Click on 'Manage apps' -> 'Upload app'
  • Upload the Spectral plugin JAR file
  • Enable the hook 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"

Change Log


  • Timeout for running Spectral
  • HTTP connection timeout
  • Ignore scanning refs of type tag


  • Update app key


  • Fix for Could not get .spectral on new branches first push
  • Handle multiple refs
  • Scan only changed files when pushing a new branch


  • [fix] not scanning when a new branch is pushed
  • Logging enhancements