Docs: Clarify Pipelines API scope parameter behavior for branches/tags

Problem to solve

The Pipelines API documentation lists the scope parameter values as: running, pending, finished, branches, tags. However, these values conflate two conceptually different filter types without explanation:

Category Values What they filter Result behavior
Pipeline State running, pending, finished Execution status Returns all matching pipelines
Ref Type branches, tags Git ref type that triggered the pipeline Returns one pipeline per ref (deduplicated)

This is confusing because:

  1. The values are presented as a flat list with no indication they behave differently
  2. branches and tags have a special deduplication behavior not mentioned
  3. Users expect branches to mean "pipelines from branches" but it actually means "latest pipeline per branch"
  4. The relationship to the pipeline's internal tag boolean attribute is not explained

Customer experience:

"What are 'scopes' in the pipelines API metadata? The 'branches' and 'tags' values feel different from 'running', 'pending', 'finished'."

The customer had to reverse-engineer the behavior from source code to understand how these parameters actually work.

Further details

From source code analysis (PipelinesFinder):

when ALLOWED_SCOPES[:BRANCHES]
  pipelines_for_refs(items.no_tag, branches)  # Returns latest per branch
when ALLOWED_SCOPES[:TAGS]
  pipelines_for_refs(items.tag, tags)         # Returns latest per tag

The pipelines_for_refs method returns only the latest pipeline (by id DESC) for each ref—this deduplication behavior is not documented.

Audience: Developers integrating with GitLab CI/CD via API

Proposal

Update the Pipelines API documentation to:

  1. Group scope values by category with clear headings:

    • Pipeline State scopes: running, pending, finished
    • Ref Type scopes: branches, tags

  2. Document the deduplication behavior:

    branches — Returns the latest pipeline (by ID) for each branch that currently exists in the repository. Only one pipeline per branch is returned.

    tags — Returns the latest pipeline (by ID) for each tag that currently exists in the repository. Only one pipeline per tag is returned.

  3. Note that ref-type scopes only include existing refs:

    Pipelines for deleted branches or tags are not included in branches or tags scope results.

  4. Clarify combinability:

    The scope parameter accepts only one value. However, scope and status can be combined (e.g., scope=branches&status=success returns the latest successful pipeline per branch).

Who can address the issue

Technical writer for CI/CD Pipelines group.

Other links/references