GitLab Well Architected
Cookbook navigation
Flows / fix-pipeline

Fix a failing pipeline with Duo

On this page
Human in the loopCI/CDPipeline troubleshootingSoftware developmentGitLab 19.4

Follow a failed pipeline through Duo's diagnosis, review its suggested fix, and check the next pipeline. Learn when a project setting is the better answer.

Type
Foundational flowOfficial guide
ScopeSingle project
Flow schemav1
Technical configuration1 trigger · 5 privileges
Triggerspipeline_hooks.failed
Privilegesread_write_filesread_only_gitlabread_write_gitlabrun_commandsuse_git

Your merge request has a red pipeline, and two jobs are failing. Are they separate problems, or did one change break both? GitLab's Fix CI/CD Pipeline flow reads the failed jobs and your changes, then proposes a repair you can review in the merge request.

The useful part isn't just getting back to green. You'll see how to connect the explanation to the code, check that the proposed change preserves what the tests were protecting, and confirm the result in a new pipeline. Sometimes the right answer is a settings change, not a code fix.

This is helpful when a failure sends you between logs, tests, and the merge request diff. If the log already gives you an obvious fix, you probably don't need a flow to make it.

You can start with a failed pipeline in your own project, or follow the worked example. It includes a small Python application with one parser defect that breaks two jobs, followed by a missing project setting. The sample files are only for following along; your own project keeps its existing code and CI configuration.

Before you begin

You'll need the Duo Agent Platform available for your project, a Developer role or higher, and runners that can execute the flow and your project's checks. GitLab's setup requirements cover the supported offerings and service-account push rules.

In the top-level group's Settings > GitLab Duo > Change configuration, check that Allow flow execution, Allow foundational flows, and Fix CI/CD Pipeline are enabled. The project also needs GitLab Duo and flow execution enabled under Settings > General > GitLab Duo. A group Owner or project Maintainer can help with those settings.

GitLab supplies the flow. There's no custom YAML to install or service account to mention.

1. Give Duo useful project context

An AGENTS.md can explain how to run your tests and what behavior needs to stay intact. Our sample instructions name the parser and event tests, explain that dates use YYYY-MM-DD, and identify the environment check as a project setting rather than a code problem.

For your project, include the commands your team actually uses and any context that isn't obvious from a failed job. For example, explain who owns a deployment setting or why a check exists. That helps Duo choose a useful next step instead of simply removing whatever makes the job fail.

2. Start from the failed merge request

Open the merge request's Overview tab and select Fix pipeline with Duo beneath the failed pipeline. GitLab adds a Session link to the activity feed. Follow it, or open AI > Sessions, to see the investigation.

You can also start the flow from these places:

  • In the merge request's Pipelines tab, select Fix pipeline with Duo on the failed pipeline's row.
  • Under Build > Pipelines, open the failed pipeline and select Fix pipeline with Duo. This also works for pipelines without a merge request.
  • In the GitLab Duo sidebar, ask Agentic Chat to fix the failed pipeline. Include the pipeline or merge request URL so it has the right target.

For automatic runs, create a trigger under AI > Triggers for Fix CI/CD Pipeline, with the event Pipeline events and Run when: Failed.

The worked example shows the button and the resulting suggestion. If the button is missing, check the individual Fix CI/CD Pipeline setting as well as Allow foundational flows; the latter doesn't enable every built-in flow.

3. Read the explanation alongside the suggestion

Return to the merge request when the Session finishes. In the parser example, Duo explains that both jobs call the same function, then suggests restoring %Y-%m-%d in src/date_parser.py. It leaves the tests and CI configuration alone.

Compare the suggestion with the failed job before applying it. Does it explain the error you saw? Does it restore the behavior the test expects? A proposal to accept month-first dates or remove the failing assertion would make a different change to the application, even if the pipeline passed afterward.

For changes within the merge request's diff, you'll usually review an inline suggestion. If the repair needs other files, GitLab can open a separate repair merge request. Review that diff in the same way.

4. Apply the repair and check CI

Choose Apply suggestion, review the commit message, and select Apply. This commits the change to your source branch; it doesn't merge the merge request.

Wait for the new pipeline. In the example, both application jobs pass after the one-line repair. The Session's local test results help explain the suggestion, while the new pipeline checks the committed change in your CI environment. Review both before deciding the work is ready to merge.

When the fix isn't in the repository

A failed job might need a project variable, restored service, or runner repair. In the second example, Duo leaves a comment naming the missing setting and the job to retry, without changing a file. That's a useful result: hard-coding a default would hide the problem.

Try both cases in the evaluation walkthrough to practice recognizing a good repair and a good explanation. For execution-image setup, long-log troubleshooting, and other starting points, see GitLab's full flow guide.

Flow files

Select a file to preview it here, or open the viewer for a larger copyable version.

Download example
Files15
  • evals15
    • fixtures12
      • changes2
        • environment-configuration1
        • product-regression1
          • src1
      • project10
        • scripts1
        • src3
        • tests3
    • templates1
evals/fixtures/changes/environment-configuration/README.mdmarkdown · 6 lines
# Event date service

This branch exercises the project-owned environment readiness check before an event-service rollout.

The check expects the non-secret CI/CD variable `PIPELINE_RESCUE_ENVIRONMENT_READY=true`. The platform team sets that variable after the target environment is available; the repository keeps the check in place.

Source file

File