GitLab Docs: Pipelines API Scope Parameter Clarification

Context

The GitLab Pipelines API includes a scope parameter that allows consumers to filter pipelines by execution state or by ref type. The documentation listed possible values such as running, pending, finished, branches, and tags.

However, the documentation did not explain that ref-based scopes behave differently from state-based scopes.

Problem

While state scopes return all pipelines matching a given state, the branches and tags scopes return only the latest pipeline for each branch or tag.

This behavior was implicit in the system but not explicitly documented, which could cause confusion for API users expecting all matching pipelines.

My Contribution

I updated the Pipelines API documentation to explicitly clarify this behavior.

The final change adds a concise clarification directly below the parameter table:

When `scope` is set to `branches` or `tags`, the API returns
    only the latest pipeline for each branch or tag ref.

The update was intentionally minimal to align with GitLab’s documentation style and to avoid unrelated changes.

Process & Iteration

An earlier merge request introduced additional structural changes. After maintainer feedback, I reworked the contribution and opened a clean follow-up merge request based on the current master branch.

This ensured:

• Minimal diff noise
• No unrelated file changes
• Clear alignment with review expectations

This experience reinforced the importance of precision, incremental changes, and responsiveness in open-source collaboration.

Reflection

Documentation clarity is critical for API usability. Making implicit behavior explicit reduces integration friction and improves developer experience.

This contribution demonstrates careful review handling, clean rebasing, and a user-centered documentation mindset.