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.

Prerequisites

To use Pipelines Troubleshooter, both Agentic Pipelines and the Failed Step Fixer system agent must be enabled for your 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.

To enable the Failed Step Fixer system agent in your Bitbucket workspace:

Select the Settings cog on the top navigation bar.
Select Workspace settings.
Select AI, and then select Agentic Pipelines.
Select the Agentic Pipelines toggle to enable Agentic Pipelines. Note: You may have already enabled this using the steps above.
Select the Failed Step Fixer toggle, so Bitbucket sets up the fix-failed-step trigger for you. You can skip this if you would rather define the trigger in your YAML yourself.

Getting started

Get started quickly with default system agents in Agentic Pipelines to automatically diagnose and resolve failed builds. It utilizes your step logs and build metadata to generate targeted fixes right when you select Apply fix without any manual YAML configuration required.

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-agent

This 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 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, which are already applied when the Failed Step Fixer toggle is selected under System agents:

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 a 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: full

Any step that sets config: default picks this up, including the pipeline Bitbucket sets up for you. See Step config.

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
System agents: Default system agents for Agentic Pipelines | Bitbucket Cloud | Atlassian Support

Was this helpful?

It wasn't accurateIt wasn't clearIt wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community