Pipelines Troubleshooter: Fixing failed steps using Agentic Pipelines
Pipelines Troubleshooter can help you to diagnose failed steps within your pipelines, and even attempts to fix the failures by leveraging agentic pipelines. This page explains how you can configure and use the ‘auto-fix’ feature from the Pipelines Troubleshooter.
Prerequisite
To use Pipelines Troubleshooter, Agentic Pipelines has to be enabled for the Bitbucket workspace
To enable agentic pipelines in your Bitbucket workspace:
Select the Settings cog on the top navigation bar.
Select Workspace settings.
Select AI, and then select AI features.
Select the Agentic Pipelines toggle to enable Agentic Pipelines.
Select the Failed step fixer toggle so Bitbucket sets up the
fix-failed-steptrigger for you. You can skip this if you would rather define the trigger in your YAML yourself.
Getting started
There are two ways to make the Apply fix button work. The quickest is to turn on the Failed step fixer toggle in your workspace settings, which lets Bitbucket set up the fix-failed-step trigger and a pipeline that runs the built-in fixing agent. Nothing goes in your YAML. See What Bitbucket sets up for you below.
The other way is to configure the fix-failed-step trigger yourself, which you need if you want your own condition, pipelines, or agent. A built-in system agent is available for use to fix your failed build utilizing metadata and logs from the failed step. This feature relies on Agentic Pipelines so make sure you have agentic pipelines enabled for the workspace.
Here is an example on how you can configure the fixer trigger using a provided system default fixing agent.
# bitbucket-pipelines.yml (minimal)
triggers:
fix-failed-step:
- condition: true # You can control when the fix it button will be available
pipelines:
- troubleshooting-pipeline # Target custom pipeline.
pipelines:
custom:
troubleshooting-pipeline:
- step:
auth:
system:
scopes: # scopes required to run the default fixing agent
- read:repository:bitbucket
- write:repository:bitbucket
- read:pipeline:bitbucket
- read:pullrequest:bitbucket
- write:pullrequest:bitbucket
script:
# It is recommended to use the provided built-in agent.
# But you can define your own agent if it doesn't suit your need.
- agent: bitbucket-default-fix-failed-step-agent
If you define the trigger yourself, it takes precedence and Bitbucket does not set anything up, even when the toggle is on.
Now you will see a new troubleshooting dialog with the Apply fix button whenever you select Suggest fix on your pipeline’s build. Carefully review if the proposed fix is reasonable, and you can let RovoDev attempt to fix the issue straightaway.
The Apply fix button triggers a new agentic pipeline using either the system agent or your own custom agent depends on the configuration provided earlier. The system-provided agent will also attempt to create a pull request if it can in order to reach a valid fix.
What Bitbucket sets up for you
When Agentic Pipelines and the Failed step fixer toggle are both on, and your bitbucket-pipelines.yml does not define a fix-failed-step trigger, Bitbucket adds configuration equivalent to this:
triggers:
fix-failed-step:
- condition: true
pipelines:
- bbc-system-failed-step-fixer
pipelines:
custom:
bbc-system-failed-step-fixer:
- step:
config: default
auth:
system:
scopes:
- read:repository:bitbucket
- write:repository:bitbucket
- read:pipeline:bitbucket
- read:pullrequest:bitbucket
- write:pullrequest:bitbucket
script:
- agent: bitbucket-default-fix-failed-step-agentThis is not written into your repository. It applies when the pipeline is parsed, so nothing is committed on your behalf.
To turn it off for a single repository, define the trigger yourself and point it at no pipelines:
triggers:
fix-failed-step:
- condition: false
pipelines: []To turn it off for the whole workspace, turn the Failed step fixer toggle off. For the full rules, see Default system agents for Agentic Pipelines.
Using the default agent
We highly recommend using the built-in agent bitbucket-default-fix-failed-step-agent. The idea is to set it and forget it, which also allows the Bitbucket Pipelines team to continuously optimize the agent using their CI/CD expertise and all diagnostic tools they have developed. Although you shouldn’t need to worry too much about the details, but in a nutshell the default fixer agent will do the following:
Gather information around the failed step using built-in tools
Propose a plan based on step build logs
Execute and verify the fix
Raise a pull request and tag the original actor, which is whoever selected the Apply fix button
The default agent needs the following permission scopes to work properly:
Read/Write for repositories so it can read code and push commits to the fixing branch
Read/Write for pull request so the agent can raise a pull request that includes the fix.
Read for the pipeline so it can download the logs from a given step.
It is not mandatory to provide all permissions, but missing permissions will result in less complete experience.
Change the environment the default agent runs in
The step Bitbucket sets up uses config: default, so you can change the image, size, and clone behavior of the built-in agent without writing a pipeline. Define a default step config:
definitions:
step-config:
default:
image: my-org/agent-base:latest
size: 2x
clone:
depth: fullAny step that sets config: default picks this up, including the pipeline Bitbucket sets up for you. See Step config.
Define your own AI agent for applying fixes
If the default agent can’t fulfill your needs, you can also provide your own agent to apply any fixes:
# bitbucket-pipelines.yml (minimal)
triggers:
fix-failed-step:
- condition: true
pipelines:
- troubleshooting-pipeline # Target custom pipeline.
definitions:
agents:
special-java-failure-fixer:
prompt: |
You are tasked to fix java build error using the following instruction:
.......
pipelines:
custom:
troubleshooting-pipeline:
- step:
auth:
system:
scopes: # scopes required to run the default fixing agent
- read:repository:bitbucket
- write:repository:bitbucket
- read:pipeline:bitbucket
- read:pullrequest:bitbucket
- write:pullrequest:bitbucket
script:
- agent: special-java-failure-fixer
Tips for customized agents used to apply fixes
When a pipeline has been triggered via the fix-failed-step trigger, we will provided you following pipelines variables to perform the troubleshooting :
Failed Pipeline UUID:
$BITBUCKET_TRIGGER_PIPELINE_UUIDFailed Step UUID:
$BITBUCKET_TRIGGER_STEP_UUIDHuman suggestion:
$BITBUCKET_FIX_FAILED_STEP_SUGGESTION
Inside the built-in pipelines MCP server, we also provide the useful tool analyzePipelineStepFailure to fetch metadata and logs for the failed step. It is highly recommended to let your agent use this tool to gather information before it starts fixing the actual problem.
Define fix-failed-step trigger with Dynamic Pipelines Providers
If your pipeline is provided by the Dynamic Pipelines Providers, you need to make sure your dynamic pipelines providers is registered on the fix-failed-step trigger. This is required for the Apply fix button to be displayed in the user interface.
Dynamic Pipelines Providers always have the highest priority so the default agent will be injected before sending to providers for transformation. The trigger and pipeline that Bitbucket sets up for you follow the same order: they are added before your configuration is sent to the providers, so a provider can change or replace them.
Limitations
The Apply fix button will not be available for deployment steps and agentic steps.
When using the default agent, all changes will be raised in pull requests for human review instead of a direct commit. You remain in control of merging.
Useful links
More about triggers and trigger conditions: Pipeline start conditions | Bitbucket Cloud | Atlassian Support
Was this helpful?