trigger a bitbucket pipeline based on a branch that has a tag

It must be acknowledged off the bat: it’s not possible. But by adding a step at the beginning of your pipeline, you can simulate the desired effect.

Out of the box, Bitbucket Pipelines allows you to trigger a build based on either a branch or a tag, but not both. Here’s an example:

pipelines:
  tags:
    '*': # match all tags
      - step:
          name: Do something
          script:
            - echo "Do something"

This pipeline will execute on all tags on all branches. But what if we want to limit it just to one branch?

When a build is triggered based on a tag, the cloned repository doesn’t include any branch information. But when a build is triggered on a branch, the cloned repository does include tag information.

To get (annotated) tags connected to the current, or HEAD, commit, we can issue this command:

$ git tag --points-at HEAD

If there’s a tag, its name will be output. If there’s no tag, nothing will be output. This is obviously ripe for automation, so I wrapped this functionality into a pipe. View the code on GitHub / view the image on Docker Hub. You can deploy it in your bitbucket-pipelines.yml like so:

pipelines:
  default:
    - step:
        name: Validate branch and tag.
        script:
          - pipe: docker://baizmandesign/tag-validator:latest
            variables:
              TARGET_BRANCH: "production"

You must pass the pipe one argument, TARGET_BRANCH. At the moment, if the commit has a tag with any name, the execution of the pipeline will continue.

drawbacks

The pipe has several moderate to serious drawbacks:

• The pipeline must be configured to run on every commit or be triggered to run on a branch.
• The pipeline will always run or always run on the given branch (unless you include “[skip ci]” or “[ci skip]” in the commit message). This means it’s eating up build minutes even if it doesn’t complete the build process due to a validation error, such as the absence of a tag on the HEAD commit.
• If the pipe detects that it’s running on the wrong branch or that a tag does not exist on the HEAD commit, the pipeline fails and triggers an email notification. This may be undesirable, since we might wish it to fail quietly, or simply stop without failing at all.

future improvements

I’d like to include a tag name or tag name pattern to target the pipeline execution conditions more precisely.