Story (Required)

As a Pipelines as Code controller trying to fetch Tekton resources (Tasks, PipelineRuns definitions) from GitHub repositories I want to utilize SHA-based caching for content fetching so that the number of redundant API calls to GitHub is reduced, mitigating the risk of hitting API rate limits and ensuring timely updates of pipeline statuses to GitHub.

This story aims to improve the resilience and efficiency of Pipelines as Code when interacting with GitHub by reducing its API call volume through targeted caching. This directly impacts users by ensuring that the status of their Konflux/Tekton pipelines is accurately and promptly reflected in GitHub PRs, avoiding confusion caused by stale "running" statuses.

Background (Required)

Users (e.g., from OpenShift Serverless team) have reported that Konflux pipeline runs appear as "running" in GitHub Pull Requests long after the actual Tekton PipelineRuns have completed. Investigation revealed these symptoms are caused by the Pipelines as Code (PaC) controller hitting GitHub API rate limits, preventing status updates to GitHub check runs.

Error logs show: "failed to post final status, moving on: failed to report status: PATCH [https://api.github.com/repos/[...]/check-runs/[...]:] 403 API rate limit still exceeded until [time], not making remote request."

The GitHub API rate limit is shared across all repositories in an organization using the same GitHub App installation. When this shared limit is exhausted, PaC cannot update the final check run status on GitHub, leading to stale pipeline status indications.

A primary contributor to API usage is frequent fetching of Tekton resources from GitHub repositories. Implementing SHA-based caching will significantly reduce these redundant API calls.

Approach (Required)

See design doc: https://docs.google.com/document/d/1is4W7bkcLoIlPiT1Z-Q_r_xbBdYWoFrQpZbbxoB9IZs/edit?tab=t.0#heading=h.3xm3w83ae4vr

Out of scope

• Implementation of HTTP ETag/If-None-Match conditional requests (focusing on SHA-based caching instead)
• Implementing user-side workarounds such as per-repository GitHub App installations
• Changes to the fundamental GitHub API rate limiting policies
• Caching of branch or tag-based references (only immutable SHA references will be cached)
• Persistent caching across controller restarts
• Broader telemetry or API load reduction efforts beyond the specified caching mechanism

   Acceptance Criteria (Mandatory)

• AC1: When PaC fetches a file from GitHub using a SHA reference for the first time, it stores the content in its in-memory cache
• AC2: On subsequent requests for the same file with the same SHA, PaC uses the cached content and does not make a GitHub API call
• AC3: Requests without a SHA or with a non-SHA reference (branch, tag) are not cached
• AC4: The cache has a configurable TTL (default 24 hours) to manage memory usage
• AC5: Cache keys properly include repository owner, name, file path, and SHA to ensure uniqueness
• AC6: Debug logging shows cache hits and misses for monitoring purposes
• AC7: The caching mechanism demonstrably reduces the number of GitHub API GET requests in scenarios with frequently accessed task definitions
• AC8: The risk of hitting GitHub API rate limits is reduced, leading to more reliable final status updates for check runs
• AC9: Unit tests verify caching behavior for SHA references vs. non-SHA references * AC10: Configuration options allow adjusting cache TTL and enabling/disabling the cache