Summary

This article addresses scenarios where a pipeline deployment is paused due to deployment restrictions on specific branches. Although pipeline runs from non-permitted branches are typically paused as expected, there are instances where pipeline deployments initiated directly from commits on allowed branches encounter failures.

Cause

Bitbucket pipelines offer the capability to run a pipeline job directly from the commits page.



When one selects the "Run Pipeline" option, the pipeline undergoes checks for deployment conditions. Eg: deployment branch restrictions. Even if the commit is associated with an allowed branch, initiating pipeline run directly from a commit will result in the pipeline being paused. In such scenarios, the pipeline attempts to perform a checkout of the specific commit rather than a git branch. This leads to a "detached HEAD" state, where the working directory is not associated with any branch. As a result, the pipeline validation fails for the allowed branch, causing the error.

Solution

To execute a pipeline deployment for a specified commit with deployment branch restrictions enabled, one option is to trigger a custom pipeline from an appropriate branch. Following this, a reset of the required commit should be performed in the pipeline step. This sequence ensures that the pipeline deployment executes on the required commit without any issues.

For illustration, consider the following sample pipeline configuration:

pipelines:
  custom:
    run-test-for-environment:
      - variables:
          - name: commithash
            default: HEAD #if no values provided it will be resetting to HEAD commit of a branch  
      - step: 
          script:
            - git reset --hard ${commithash}
            - echo "build is running"

Steps:

1. In Bitbucket, choose a repo and go to Branches.
   

2. Choose the branch you want to run a custom pipeline for.

3. Click (...), and select Run pipeline for a branch.
   
   
   
   

4. Choose the custom pipeline (eg: run-test-for-environment), enter the commit hash details and click Run:
   
   

By following this sequence, the pipeline deployment will be executed successfully without encountering errors related to detached HEAD states or validation issues.