Story (Required)

As a Pipelines-as-Code operator/developer trying to resolve remote pipeline/task URIs referenced in Bitbucket Data Center, I want the Bitbucket Data Center provider to support parsing browse/raw file URLs (including refs via query parameters) and fetch file contents for same-host URIs so that the resolver can retrieve remote pipelines/tasks from private Bitbucket Data Center repositories.

This will allow PAC to fetch task/pipeline files referenced by Bitbucket Data Center links in private repos and close the current gap in provider support that prevents customers from using private Bitbucket Data Center repositories as remote pipeline sources.

Background (Required)

• Customer report: customer reported that the PAC resolver fails to fetch remote pipelines from a private Bitbucket Data Center repository (Support case: https://access.redhat.com/support/cases/04249123). The documentation currently provides guidance for GitHub/GitLab but lacks details for Bitbucket Data Center.
• Internal discussion recorded in Slack: https://redhat-internal.slack.com/archives/CSPS1077U/p1757564746804439
• Team agreed this is a feature request and an RFE was created to track it (RFE ticket created by the team).

Out of scope

• Bitbucket Cloud (this request targets Bitbucket Data Center/server only)
• Non-file UI pages (pull request UI pages, diffs, etc.)
• Extensive performance/streaming optimizations or binary-specific handling
• Broad provider parity for other git platforms (separate work tracked independently)
• Integration tests against a customer’s production Bitbucket Data Center instance (can be added later as part of QA)

Approach (Required)

• Implement provider-side support to recognize Bitbucket Data Center file URLs (browse/raw) and extract repository context and optional reference information.
• Ensure same-host checks to prevent resolving files from untrusted external hosts.
• Use existing provider mechanisms to fetch raw file content from the referenced repository and revision (or default branch when no revision provided).
• Add unit tests to cover parsing, host verification, ref handling (including URL-encoded refs), and file retrieval behaviors.
• Update resolver documentation to mention Bitbucket Data Center support and any configuration or RBAC/credentials requirements for private repos.

Dependencies

• Access to Bitbucket Data Center API client logic or libraries already used by the provider
• Host-comparison/util code for same-host verification
• Mechanism to fetch raw file content from Bitbucket Data Center using appropriate credentials
• Test harness/mocks for Bitbucket Data Center to validate unit tests
• CI to run unit tests; QA environment for integration validation (if available)
• Product documentation owner to update the resolver docs

Acceptance Criteria (Mandatory)

• The Bitbucket Data Center provider accepts browse/raw file URLs from the same host as the event and returns the referenced file content to the resolver.
• The provider supports optional reference parameters (e.g., branch/name encoded in query param) so that files at a specific ref can be fetched.
• If no ref is provided, the provider fetches from the repository’s default branch.
• Host mismatch detection prevents fetching files from different hosts and returns a non-allowed result without performing the fetch.
• Parsing errors or malformed Bitbucket Data Center URLs return clear, descriptive errors.
• Unit tests cover success and failure scenarios: browse URL with and without ref, raw URL with and without ref, host-disallowed cases, and malformed URLs.
• Documentation updated to document Bitbucket Data Center support and any configuration steps for private repositories.
• Changes pass CI and review, and are included in a release pipeline.

Edge cases to consider:

• URL-encoded branch names (e.g., feature%2Fname)
• File paths with multiple segments and special characters
• Repositories configured with non-standard default branches
• Credential/permission failures when accessing private repos

INVEST Checklist

Dependencies identified
Blockers noted and expected delivery timelines set - Unknown (to be determined)
Design is implementable
Acceptance criteria agreed upon
Story estimated - Unsatisfied (estimation TBD)

Legend

Unknown

Verified

Unsatisfied

Done Checklist

• Design documented and reviewed
• Implementation completed, reviewed and checked in
• Unit test coverage added and running green in CI
• Integration/QA validation completed (if applicable)
• Resolver documentation updated to include Bitbucket Data Center guidance
• Acceptance criteria met and verified

References / Context:

• Slack: https://redhat-internal.slack.com/archives/CSPS1077U/p1757564746804439
• Support case: https://access.redhat.com/support/cases/04249123
• RFE tracking to be linked here (created by the team)