Story (Required)

As a developer or SRE troubleshooting Pipelines-as-Code, I want to enable detailed logging for all GitHub API calls so that I can easily diagnose issues related to rate-limiting, permissions, or other API interaction problems.

This feature introduces a new debugging capability that provides deep insight into the interactions between Pipelines-as-Code and the GitHub API. By setting the controller's log level to 'debug', users can now see the duration, requested URL, and remaining rate-limit for every API call, significantly improving the troubleshooting experience for complex issues.

Background (Required)

Currently, debugging GitHub API interactions within Pipelines-as-Code can be challenging. There is no built-in mechanism to inspect the specifics of each API call, such as the exact URL requested, the execution time, or the impact on the GitHub rate limit. This lack of visibility makes it difficult to troubleshoot issues like invalid token permissions, 404 errors for teams or collaborators, or intermittent failures due to rate-limiting.

This story introduces a profiling utility that wraps all GitHub API calls. When debug logging is enabled, it provides detailed information for each call, making the debugging process more efficient and transparent.

Out of scope

• This logging enhancement is only for the GitHub provider. Other providers (e.g., GitLab, Bitbucket) are not affected.
• The detailed API logs are only generated at the `debug` log level. They will not appear at the `info` level or higher to avoid cluttering production logs.
• This change does not introduce any new metrics, but it ensures existing API usage metrics continue to function correctly.

Approach (Required)

Refactor code to instrument github call

Dependencies

• None

Acceptance Criteria (Mandatory)

• Given the `pac-config-logging` ConfigMap has `loglevel.pipelinesascode` set to `info`,
• When a PipelineRun is processed,
• Then no detailed GitHub API logs (showing URL, duration, rate-limit) should be present in the controller logs.
• Given the `pac-config-logging` ConfigMap has `loglevel.pipelinesascode` set to `debug`,
• When a PipelineRun is processed,
• Then every GitHub API call must generate a corresponding debug log line.
• Given debug logging is enabled,
• When a GitHub API call is made,
• Then the resulting log line must contain the request URL, the call duration, and the remaining API rate-limit.
• Given the changes are merged,
• Then all types of GitHub API calls (e.g., getting content, listing files, creating statuses, checking collaborators) within the provider must be wrapped by the new profiling utility.
• Given the changes are merged,
• Then the documentation for logging must exist in the new `install/logging.md` file and be removed from `install/settings.md`.
• Given the new logging documentation,
• Then a user must be able to understand how to enable the detailed API logging feature.

INVEST Checklist

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

Legend

• [ ] Unknown
• [x] 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