Story (Required)

As a Pipelines-as-Code user trying to run a pipeline on a merge request for a private GitLab repository I want to receive a clear error message when my configured token lacks the necessary permissions to access the repository, so that I can quickly diagnose and fix the authentication issue instead of being misled.

The current error message, ".tekton/ directory doesn't exist in repository's root directory," is cryptic and misleading. It incorrectly suggests a problem with the repository's file structure, when the actual root cause is an authentication/authorization failure. This story aims to improve the customer experience by providing an accurate and actionable error message that points directly to the token permission issue.

Background (Required)

When a user configures Pipelines-as-Code (PaC) for a private GitLab repository, they provide a personal access token via a Secret referenced in the `Repository` Custom Resource (CR). If this token does not have sufficient permissions (e.g., the `read_repository` scope) to clone or inspect the repository's contents, the GitLab driver fails to find the `.tekton/` directory.

Instead of reporting the underlying access error, PaC bubbles up a confusing message about a missing `.tekton/` directory. This sends the user on a wild goose chase, trying to debug their repository layout rather than their credentials.

Out of scope

• Automatically fixing token permissions or scopes.
• Changes to other Git providers (e.g., GitHub, Bitbucket). This story is specific to the GitLab driver.
• Modifying the fundamental authentication mechanism.

Approach (Required)

The GitLab driver should be modified to correctly distinguish between a failure to find the `.tekton/` directory in an accessible repository and a failure to access the repository itself due to permission issues.

When an access failure is detected, the driver must surface a specific, user-friendly error message that guides the user to check their token's permissions. This error should be clearly reflected in the final commit status update for the merge request.

Dependencies

• None. This is a self-contained change within the Pipelines-as-Code GitLab driver.

Acceptance Criteria (Mandatory)

AC1: Misleading error is replaced with a clear auth error

• Given a private GitLab repository is configured with a PaC `Repository` CR.
• And the secret referenced in the CR contains a GitLab token that does not have `read_repository` permissions.
• When a merge request is created in that repository.
• Then the associated commit status in GitLab must be marked as `failed`.
• And the failure message must clearly indicate an access/permission issue with the token, and must not mention a missing `.tekton/` directory.

AC2: Valid token continues to work

• Given a private GitLab repository is configured with a PaC `Repository` CR.
• And the secret referenced in the CR contains a valid token with sufficient permissions.
• When a merge request is created.
• Then the pipeline execution must proceed as expected without any authentication errors.

INVEST Checklist

 Dependencies identified
 Blockers noted and expected delivery timelines set
 Design is implementable
 Acceptance criteria agreed upon
 Story estimated

Legend

 Unknown
 Verified
 Unsatisfied

Done Checklist

• Code is completed, reviewed, documented and checked in
• Unit and integration test automation have been delivered and running cleanly in continuous integration/staging/canary environment
• Continuous Delivery pipeline(s) is able to proceed with new code included
• Customer facing documentation, API docs etc. are produced/updated, reviewed and published
• Acceptance criteria are met