How do you pin pipes safely in Bitbucket Pipelines?

Pin every pipe in bitbucket-pipelines.yml to an exact version, such as atlassian/aws-s3-deploy:1.1.0, never a floating tag. A pipe is a Docker container that runs inside your build with access to your variables, so changing what a tag points to changes what runs with your secrets.

What is a pipe, in security terms?

Atlassian's documentation says a pipe is referenced with the pipe keyword in the format vendor/pipe-name:version. A custom pipe is a Docker container whose entrypoint is a script. So a pipe is third party code that runs in your pipeline step, reads the variables you pass, and can see anything else that step can see.

That is the same trust model as a third party CI action elsewhere. If the code behind a reference changes, your build changes with it, without a commit in your repository.

Why does pinning matter?

The Atlassian page states the best practice: always specify exact pipe versions for reproducibility. Reproducibility is also a security property. If the pipe version is fixed, the code that handles your deploy credentials changes only when you change the line.

Constructed example: a pipeline calls a deploy pipe by a loose tag. The publisher's account is later compromised and the tag is moved to a build that sends environment variables to a remote server. Your next run ships your cloud keys out. With an exact version, you would still run the old code until a reviewer approved a bump. This is a hypothetical, but it is the same shape as real tag redirection attacks in other CI systems.

One caveat from the docs: the page does not describe referencing a pipe by image digest. A version string names a tag, and tags can in principle be re-pointed by whoever controls the registry entry. If your policy needs immutability, check whether your own mirrored or custom pipes can be referenced by digest in your setup, and verify that before relying on it.

What other settings help?

The documentation also recommends:

• Store sensitive values as secured repository variables, not plain text.
• Check that credentials have only the permissions they need.
• Test pipe configuration in staging before production.

Add to that the usual controls: separate credentials per environment, deploy credentials restricted to protected branches, and short lived cloud tokens where your provider supports them.

How do you manage upgrades without freezing?

Pinning does not mean never updating. Pick a rhythm.

1. Keep a list of every pipe the organization uses, with owner and version.
2. When a new version is released, read its changelog and, for important pipes, its source.
3. Update the version in a pull request, run it in staging, and merge after review.
4. For custom pipes you build, publish from a protected branch and tag releases with exact versions.

A dependency bot can open the version bump pull request for you, but check that your bot supports Bitbucket pipes before counting on it.

What to do

1. Search all repositories for pipe: lines and list the vendor, name and version.
2. Replace any missing or floating version with an exact version.
3. Prefer pipes from vendors you can name, and read the source of the rest.
4. Move secrets to secured variables and trim permissions.
5. Restrict who can edit bitbucket-pipelines.yml on protected branches.
6. Review upgrades as pull requests, with a staging run.
7. Re-run the search monthly to catch drift.

Safeguard's CI integration can gate builds on dependency risk. See the CI/CD actions demo.

Quick check

Sources

• Use pipes in Bitbucket Pipelines, Atlassian Support

Last reviewed: 18 October 2026.