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 Bibucket workspace
To enable agentic pipelines in your Bitbucket workspace:
Select the Settings cog (cog icon) on the top navigation bar.
Select Workspace settings.
Select Atlassian Integrations, and then select Atlassian Intelligence.
Select the Agentic Pipelines toggle switch.
Getting started
To use auto-fix, you must configure the fix-failed-step trigger in your Bitbucket YAML file, so Bitbucket can launch the necessary fix in an agentic pipeline once you select the Apply fix button. 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
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.
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.
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.
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?