How to fix Merge request cannot be merged: pipeline failed in Git

First, identify which specific jobs caused the pipeline to fail:

1. Navigate to your merge request in GitLab
2. Click on the Pipelines tab
3. Click on the failed pipeline (shown with a red X)
4. Review the job list to find which jobs failed

# Example pipeline view:
✓ build        passed
✓ lint         passed
✗ test         failed (exit code 1)
○ deploy       skipped

Click on the failed job to view its logs and understand the failure reason.

If the pipeline failure is due to actual code issues, fix them and push:

# View the failing tests or issues locally first
npm test
# or
pytest
# or
make test

# After fixing the issues
git add .
git commit -m "fix: resolve failing tests"
git push origin your-branch

This triggers a new pipeline automatically. Common fixes include:
- Fixing failing unit tests
- Resolving linting errors
- Updating dependencies with security vulnerabilities
- Fixing compilation errors

If the failure was due to a transient issue (network timeout, flaky test, resource exhaustion), retry the failed jobs:

Retry individual failed jobs:
1. Go to the failed pipeline
2. Click on the failed job
3. Click Retry button in the top right

Re-run the entire pipeline:
1. Navigate to the merge request
2. Go to the Pipelines tab
3. Click Run pipeline button

You can also use GitLab quick actions in a comment:

/rebase

This rebases the branch and triggers a new pipeline.

Invalid CI/CD configuration causes immediate pipeline failures. Validate your configuration:

Using the GitLab CI Lint tool:
1. Navigate to Build > Pipeline editor in your project
2. Click Validate tab
3. Paste your .gitlab-ci.yml content
4. Check for syntax errors

Common configuration issues:

# Wrong: Invalid YAML syntax (tabs instead of spaces)
test:
	script: npm test  # Tab character - use spaces!

# Correct:
test:
  script: npm test

# Wrong: Missing required 'script' keyword
test:
  - npm test

# Correct:
test:
  script:
    - npm test

From the command line:

# Use the GitLab CI Lint API
curl --header "PRIVATE-TOKEN: <your_token>" \
  "https://gitlab.com/api/v4/ci/lint" \
  --form "[email protected]"

If your project has "Pipelines must succeed" enabled but no pipeline is configured, you have two options:

Option 1: Add a minimal pipeline
Create a .gitlab-ci.yml file:

# Minimal passing pipeline
stages:
  - test

placeholder:
  stage: test
  script:
    - echo "Pipeline passed"

Option 2: Disable the setting (if appropriate)
1. Navigate to Settings > Merge requests
2. Under "Merge checks", find "Pipelines must succeed"
3. Uncheck the option
4. Click Save changes

Note: Disabling this setting removes an important safety check. Only do this if you have other mechanisms to ensure code quality.

When both merge request pipelines and branch pipelines run, GitLab only checks merge request pipelines for the "must succeed" requirement:

Symptoms:
- Branch pipeline shows green/passed
- Merge request still blocked
- Duplicate pipelines appearing

Solution: Use workflow:rules to prevent duplicate pipelines:

workflow:
  rules:
    # Run pipeline for merge requests
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    # Run pipeline for default branch
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    # Run pipeline for tags
    - if: $CI_COMMIT_TAG

stages:
  - test
  - build

test:
  stage: test
  script:
    - npm test

This ensures only one pipeline type runs, avoiding confusion about which status matters.

If using merge trains and the merge train pipeline fails:

Re-add to merge train:
1. Ensure your merge request pipeline is passing
2. Use the quick action in a comment:

/merge

Or click Start merge train / Add to merge train button.

Check for merge conflicts with other MRs:
Merge trains run merged results pipelines. If your MR conflicts with another MR already in the train, the pipeline may fail.

# Rebase onto the latest target branch
git fetch origin main
git rebase origin/main
git push --force-with-lease origin your-branch

Note: The merge train pipeline tests your changes merged with all MRs ahead of yours in the queue. A failure might not be from your code alone.

Sometimes GitLab cannot retrieve the pipeline status correctly, especially if:
- The MR was created, closed, modified, then reopened
- There were connectivity issues during pipeline execution
- The GitLab Runner had issues reporting status

Fix by refreshing the MR state:
1. Close the merge request
2. Reopen it immediately
3. The pipeline status should now be retrieved correctly

Alternative: Trigger a new pipeline:

# Create an empty commit to trigger a new pipeline
git commit --allow-empty -m "chore: trigger pipeline"
git push origin your-branch

This forces GitLab to run a fresh pipeline and update the status.