Validate remote include response as YAML before processing

Rajendra Kadamrequested to merge
585871-improve-error-message into master

What does this MR do and why?

Detects HTML content in the YAML loader and normalizes the Psych::SyntaxError message to Invalid configuration format instead of exposing raw parser errors like mapping values are not allowed in this context.

Problem

When a remote CI include URL points to a private or inaccessible resource, the server returns a 302 redirect to a sign-in page. HTTParty follows the redirect and receives an HTML response with HTTP 200, bypassing the existing >= 400 status code check. The HTML body is then passed to the YAML parser, which raises Psych::SyntaxError with a cryptic message that misleads users into thinking their CI configuration syntax is wrong.

Root cause

The difference in error messages comes from how YAML.safe_load handles different non-YAML content:

  • HTML sign-in pages raise Psych::SyntaxError → raw error message leaks through (mapping values are not allowed in this context)
  • Other non-YAML content (e.g. Markdown) parses as a YAML string → caught by unless hash? → produces clean Invalid configuration format

Approach

  • Added a separate rescue Psych::SyntaxError block in lib/gitlab/config/loader/yaml.rb
  • Only normalizes the error when the content is detected as HTML (starts with <!doctype html or <html) via html_content? helper
  • Genuine YAML syntax errors preserve their original detailed Psych error messages
  • Gated behind ci_yaml_syntax_error_normalization feature flag for safe rollout
  • No double parsing overhead — detection is a simple string prefix check

Feature flag rollout plan

Enable for a small percentage of requests first and observe for any issues before full rollout.

FF issue - [FF] `ci_yaml_syntax_error_normalization` -- No... (#596154) • Rajendra Kadam • 19.0

References

Improve error message for inaccessible remote C... (#585871) • Rajendra Kadam • 19.0

Screenshots

Before After
Screenshot_2026-04-09_at_2.50.56_PM Screenshot_2026-04-09_at_2.53.40_PM

How to set up and validate locally

  1. Create a private project with a YAML template file
  2. In a public project, use include:remote pointing to the private project's file URL
  3. With the feature flag disabled, observe the cryptic YAML parse error
  4. Enable the feature flag: 
    Feature.enable(:ci_yaml_syntax_error_normalization)
  5. Observe the improved Invalid configuration format error message
  6. Verify genuine YAML syntax errors still show detailed messages (e.g. invalid: yaml: syntax)

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Rajendra Kadam

Merge request reports