Commit and push validation

Jira Hooks for Bitbucket Cloud supports local commit and push validation through a Validation API and lightweight Git hook scripts.

This allows developers to validate commits and pushes before changes reach Bitbucket Cloud. The validation uses the same Process Guardian rules that are configured in Jira Hooks for Bitbucket, for example issue key checks, JQL checks, naming conventions, and consistency checks.

This is useful because Bitbucket Cloud currently does not provide a cloud-side mechanism to block pushes before they are accepted. Local Git hooks provide the earliest possible validation point in the developer workflow.

Configure the Validation API

Before the API can be used, it must be enabled and configured in Jira Hooks for Bitbucket Cloud in the Process Guardian section. The Validation API can be configured either at the repository level or at the workspace level.

Repository configuration

A repository-level configuration does not create a separate Validation API endpoint. The same Validation API is used in both cases. The primary benefit of a repository-level configuration is that it generates a dedicated validation token for a specific repository. This allows access to be managed independently for each repository.

The generated Validation API URL automatically includes the repository identifier as a query parameter.

As a result, Git hooks, CI/CD pipelines, and custom integrations do not need to provide the repository information separately when calling the API.

Workspace configuration

A workspace-level configuration uses the same Validation API but generates a generic endpoint that is not bound to a specific repository.

In this case, the repository must be supplied by the client during the request, either through:

• the repoSlug URL parameter

• the repoSlug field in the request payload

• the repositoryUuid field in the request payload

This allows a single validation endpoint and token to be shared across multiple repositories within the same workspace.

Typical use cases:

• Centralized Git hook deployments

• Shared CI/CD validation services

• Workspace-wide automation

• Simplified administration across multiple repositories

Configuration status

Each Endpoint has its current status:

When a configuration is in the Not configured state, local Git hooks, CI/CD pipelines, and custom integrations cannot authenticate against the Validation API.

Generate a validation token

Select Configure to generate a validation token and enable the Validation API. After selecting Configure, Jira Hooks for Bitbucket displays the generated authentication token together with the Validation API endpoint URL.

The dialog contains:

The displayed values correspond to:

JHFB_ENDPOINT and JHFB_SECRET

used by local Git hooks, CI/CD pipelines, and custom integrations.

Store the token securely

The authentication token cannot be viewed again after the dialog is closed.

Store the token immediately in a secure location, for example:

• A password manager

• A secret management system

• CI/CD secret storage

• Local hook configuration files

Lost token

If the authentication token is lost, forgotten, or accidentally deleted, it cannot be recovered.

In this case:

1. Select Reset token

2. Generate a new token

3. Update all Git hooks, CI/CD pipelines, and custom integrations with the new secret

After a token reset, all previous tokens become invalid immediately.

Do it by your own

The provided Git hooks are the recommended way to integrate local commit and push validation. They require no custom development and can be installed within minutes.

If you want to build your own hooks, integrate the validation into a CI/CD pipeline, or develop a custom client, the following sections describe the Validation API, request payloads, authentication, and response format in detail.

Required configuration

The local hooks require two configuration values:

Example:

JHFB_ENDPOINT="https://<your-validation-endpoint>"
JHFB_SECRET="<your-hmac-secret>"

Payload structure

The Validation API expects a JSON payload with branch and commit information.

Fields

Commit object

Each commit object can contain:

Example payload for validation

{
  "branchName": "feature/ABC-123-local-check",
  "triggerType": "COMMIT/PUSH",
  "locale": "en-US",
  "commits": [
    {
      "hash": "0000000000000000000000000000000000000000",
      "message": "feat(ABC-123): add local validation",
      "authorDisplayName": "Jane Developer"
    }
  ]
}

Calling the Validation API with curl

The Validation API requires an HMAC-SHA256 signature in the x-hub-signature-256 header.

The signature must be calculated over the raw JSON request body using JHFB_SECRET.

BODY='{"branchName":"feature/ABC-123-local-check","triggerType":"PUSH","locale":"en-US","commits":[{"hash":"f00ba41234abcd1234abcd1234abcd1234abcd12","message":"feat(ABC-123): add local validation","authorDisplayName":"Jane Developer"}]}'

SIGNATURE="sha256=$(printf %s "$BODY" | openssl dgst -sha256 -hmac "$JHFB_SECRET" -hex | sed 's/^.* //')"

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-hub-signature-256: $SIGNATURE" \
  --data "$BODY" \
  "$JHFB_ENDPOINT"

If the endpoint URL does not already identify the repository, pass the repository as a query parameter or include repoSlug or repositoryUuid in the request body.

Result

The API returns a structured validation result.

The response includes:

If the result is blocking, the local hook can stop the commit or push.

HTTP status codes

The Validation API uses standard HTTP status codes to indicate whether the request itself was processed successfully. Validation results such as PASS, WARNING, SKIP, or BLOCK are returned in the response body and are independent of the HTTP status code.

Important

A successful HTTP response does not necessarily mean that the validation passed.

For example, a request may return:

{
  "result": "BLOCK"
}

together with:

HTTP/1.1 200 OK

In this case, the request itself was valid and processed successfully, but the evaluated Process Guardian rules blocked the operation.