# Fix CI/CD Pipeline Flow

{{< details >}}

- Tier: [Free](../../subscriptions/gitlab_credits.md#for-the-free-tier), Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

- Introduced as [an experiment](../../policy/development_stages_support.md) in GitLab 18.4 [with feature flags](../../administration/feature_flags/_index.md) named `duo_workflow_in_ci` and `ai_duo_agent_fix_pipeline_button`. `duo_workflow_in_ci` is enabled by default. `ai_duo_agent_fix_pipeline_button` is disabled by default. These flags can be enabled or disabled for the instance or project.
- Enabled on GitLab.com and GitLab Self-Managed in GitLab 18.5.
- Feature flag `ai_duo_agent_fix_pipeline_button` [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/205086) in GitLab 18.5.
- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/work_items/585273) in GitLab 18.8. Feature flag `ai_duo_agent_fix_pipeline_button` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/216681). Feature flag `duo_workflow_in_ci` was removed in GitLab 18.9.
- Available on the Free tier on GitLab.com with GitLab Credits in GitLab 18.10.
- Fixes to pipelines associated with a merge request [changed](https://gitlab.com/groups/gitlab-org/-/work_items/21837)
  to apply as code suggestions in GitLab 19.1
  [with a feature flag](../../administration/feature_flags/_index.md) named `fix_pipeline_next`.
  Enabled on GitLab.com for a subset of users.
- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/241608) in GitLab 19.2. Feature flag `fix_pipeline_next` removed.

{{< /history >}}

The Fix CI/CD Pipeline Flow diagnoses and proposes fixes for issues in your GitLab CI/CD pipeline.
To diagnose failures, the flow examines:

- Pipeline logs, including error messages, failed job outputs, and exit codes.
- Merge request changes that could have caused the failure.
- Repository contents, for identifying syntax, linting, or import errors.
- Script errors, including command failures, missing executables, or permission issues.

How the flow applies fixes depends on the pipeline context:

- If the pipeline is associated with a merge request, the flow applies inline code suggestions
  on the source branch. You can review and apply the suggestions directly from the merge request.
  - If the fix requires changes to files outside the current merge request diff, the flow
    creates a new merge request instead.
- If the pipeline is not associated with a merge request, the flow creates a new merge request
  that contains the fix.

In some cases, instead of attempting a fix, the flow posts a comment that describes
the failure and possible next steps.
This happens when the pipeline is associated with a merge request, for example:

- Insufficient context exists to determine a reliable fix.
- The failure is security-sensitive and should be reviewed by a person.
- The failure category is not actionable by the flow.

When a session starts and completes, the flow posts system notes to the merge request
with a link to the session. This flow is available in the GitLab UI only.

This flow is the recommended path if you use the GitLab Duo Agent Platform and want to
fix a failed pipeline automatically.
It's a separate experience from
[Root Cause Analysis](../../user/gitlab_duo_chat/examples.md#troubleshoot-failed-cicd-jobs-with-root-cause-analysis),
a GitLab Duo Chat feature to troubleshoot single-job failures.

## Prerequisites

- Meet the [prerequisites for the GitLab Duo Agent Platform](../../user/duo_agent_platform/_index.md#prerequisites).
- Turn on **Allow foundational flows** and **Fix CI/CD Pipeline** [for the top-level group](../../user/duo_agent_platform/flows/foundational_flows/_index.md#turn-foundational-flows-on-or-off).
- Have the Developer, Maintainer, or Owner role for the project.
- Have an existing failed pipeline.
- [Configure push rules to allow a service account](../../user/duo_agent_platform/troubleshooting.md#configure-push-rules-to-allow-a-service-account).
- [Configure your own runners](../../user/duo_agent_platform/flows/execution/_index.md#configure-runners-to-execute-flows) or turn on [GitLab hosted runners](../runners/hosted_runners/_index.md) for your project.
- Recommended. Create an [agent configuration file](../../user/duo_agent_platform/flows/execution/_index.md#create-the-agent-configuration-file) so the flow has access to your project's toolchain and dependencies.

## Fix the pipeline in a merge request

{{< history >}}

- Using a flow in a GitLab Duo Agentic Chat conversation [introduced](https://gitlab.com/groups/gitlab-org/-/work_items/20484) in GitLab 19.2 [with a feature flag](../../administration/feature_flags/_index.md) named `agentic_foundational_flow_tool`. Enabled by default.
- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/work_items/605446) in GitLab 19.5. Feature flag `agentic_foundational_flow_tool` removed.

{{< /history >}}

To fix the CI/CD pipeline in a merge request:

1. In the top bar, select **Search or go to** and find your project.
1. In the left sidebar, select **Code** > **Merge requests** and open your merge request.
1. Use one of these methods to fix the pipeline:
   - Select the **Overview** tab and, under the failing pipeline, select
     **Fix pipeline with Duo**.
   - Select the **Pipelines** tab and, in the rightmost column, select
     **Fix pipeline with Duo** ({{< icon name="tanuki-ai" >}}).
   - In the GitLab Duo sidebar, open a new or existing Agentic Chat conversation.
     Ask Agentic Chat to fix the pipeline.
1. To monitor progress, in the left sidebar, select **AI** > **Sessions**.

   If you are in Agentic Chat, you can also do the following:
   - See the progress in the Chat conversation.
   - Select **View Agent Session** in the conversation.

When the session is complete, the flow adds code suggestions to the merge request,
or a comment describes possible next steps.

## Fix other CI/CD pipelines

To fix a CI/CD pipeline that is not associated with a merge request:

1. Select **Build** > **Pipelines**.
1. Select your failing pipeline.
1. In the upper-right corner, select **Fix pipeline with Duo**.
1. To monitor progress, select **AI** > **Sessions**.

## Use `AGENTS.md` to customize the flow

The flow reads repository-specific instructions from an
[`AGENTS.md`](../../user/duo_agent_platform/customize/agents_md.md) file in your repository.
You can use `AGENTS.md` to customize behavior such as:

- Commit message format for the changes the flow commits.
- Merge request metadata, such as labels and description, for merge requests the flow creates.
- How to classify and treat specific types of failures.
- How to handle repeated failures of the same type, to prevent the flow from making the
  same unsuccessful fix more than once.

For example:

```markdown
## Fix pipeline merge requests

When opening a merge request as part of the Fix Pipeline flow (the title contains [FixPipeline]),
apply labels based on the following failed pipeline scenarios:

- Pipeline failed on merge_request: apply "pipeline::tier-1". This runs the cheaper tier-1
  pipeline instead of the full default pipeline.
- Pipeline failed on the default_branch (main): apply both "pipeline::expedited" and
  "main:broken". Do not apply pipeline::tier-1 in this case.
- Pipeline failed on other branches: apply "pipeline::tier-1". Same treatment as the
  merge_request case.
```

For example, to handle migration failures:

```markdown
## Migration failures

If a pipeline fails because of a database migration:

- Run `bin/rails db:migrate:status` to check the current migration state before attempting
  a fix.
- Do not edit or delete past migration files.
- If the migration cannot be safely reversed, post a comment describing the issue instead
  of attempting a fix.
```

## Known issues

- The AI gateway processes only the last 150 KiB of job logs. If your job produces extensive
  output, the flow might not capture relevant failure information that appears earlier in the log.
  See the following section for workarounds.
- The flow cannot always verify package installation in the sandboxed runtime environment.
  If dependencies are missing, you can customize the default flow image. See
  [change the default Docker image](../../user/duo_agent_platform/flows/execution/images.md#change-the-default-docker-image).
- Repository instructions in `AGENTS.md` influence the flow's behavior but are not guaranteed
  to be followed in every case.

## Troubleshooting

When working with the Fix CI/CD Pipeline Flow, you might encounter the following issues.

### Flow cannot identify the root cause of a failure

The flow might not identify the root cause of a pipeline failure.

This issue occurs when job logs exceed 150 KiB. The AI gateway processes only the last 150 KiB,
so relevant failure information that appears earlier in the log might not be captured.

To work around this issue, try the following:

- Reduce verbose output by removing debug logging and progress indicators.
- Redirect non-critical output using shell redirection (`> /dev/null`).
- Add a summary step at the end of your script that echoes key error messages.
- Use `after_script` to output diagnostic information after the main script completes.
- Split verbose jobs into smaller, focused jobs with more concise logs.

### Session failed to start

The session for the Fix CI/CD Pipeline Flow fails, and on the session page (**AI** > **Sessions**),
the `Session failed to start` alert appears.

Two pipelines are involved: the pipeline that failed, and the
[workload pipeline](pipeline_types.md#workload-pipeline) the flow creates
to fix it. Check the status of the job in the workload pipeline.

For causes and how to resolve them, see
[a flow's job or session fails to start](../../user/duo_agent_platform/troubleshooting.md#a-flows-job-or-session-fails-to-start).

### Fix pipeline with Duo button does not appear

You meet the [prerequisites](#prerequisites), but the **Fix pipeline with Duo** button
does not appear.

This issue occurs because the button depends on settings across three separate pages (GitLab
Duo, the Agent Platform, and foundational flows).
A setting turned on at one level does not guarantee it is on at every level below it.

To resolve this issue, recheck each requirement:

- [GitLab Duo](../../user/duo_agent_platform/turn_on_off.md#turn-gitlab-duo-on-or-off) or
  [GitLab Duo Core](../../user/duo_agent_platform/turn_on_off.md#turn-gitlab-duo-core-on-or-off) is turned on.
- The [Agent Platform is turned on](../../user/duo_agent_platform/turn_on_off.md#turn-gitlab-duo-agent-platform-on-or-off).
- **Allow foundational flows** and **Fix CI/CD Pipeline** are turned on for the top-level group
  and, on GitLab Self-Managed, the instance.

## Give feedback

The team is actively improving the Fix CI/CD Pipeline Flow. To report issues or suggest improvements, leave your feedback in [feedback issue 601991](https://gitlab.com/gitlab-org/gitlab/-/work_items/601991).

