kubechecks

Archive mode replaces Git protocol operations with HTTPS REST API calls to the respective Version Control System (VCS).

GitHub Implementation

• Mechanism: Downloads a ZIP archive of the merge commit SHA via the GitHub API.
• Endpoint: https://api.github.com/repos/{owner}/{repo}/zipball/{sha}
• Authentication: Uses Authorization: Bearer <token>.
• File Detection: Uses the GET /repos/{owner}/{repo}/pulls/{number}/files endpoint to identify changed files.

GitLab Implementation

• Mechanism: Downloads a preview merge via a special merge ref.
• Endpoint: https://gitlab.com/api/v4/projects/{project_encoded}/repository/archive.zip?sha=refs/merge-requests/{iid}/merge
• Authentication: Uses PRIVATE-TOKEN: <token>.
• File Detection: Uses the GET /projects/{id}/merge_requests/{iid}/diffs endpoint.
• Note: GitLab uses the special refs/merge-requests/<iid>/merge ref because the merge_commit_sha is only available after the MR is merged.

The kubechecks architecture is built on three primary abstractions that allow it to remain VCS-agnostic:

Client

Acts as the entry point for the process. A Client implementation is responsible for:

• Validating incoming webhooks and their payloads.
• Converting VCS-specific webhook payloads into the internal Repo representation.
• Communicating back to the remote VCS (e.g., posting or updating comments on a PR/MR).
• Supported providers: GitHub, GitLab.

Repo

An internal representation of a Pull/Merge Request. It contains metadata required to perform local git operations, including:

• The HEAD SHA of the PR/MR branch.
• The base/target branch information.
• Git metadata (username/email).
• The ability to locally clone the repository at the specified SHA.

CheckEvent

The orchestrator of a single execution run. It takes a Client and a Repo and:

• Determines which applications within the repository are affected by the PR/MR.
• Runs the check suites for affected applications concurrently.
• Aggregates individual application reports into a single comprehensive report.
• Instructs the Client to update the PR/MR comment with the latest status.

The Kubechecks queue system uses a hybrid concurrency model to manage PR check requests. It provides per-repository sequential processing and cross-repository parallelism.

Mental Model

• Sequential per Repo: For any single repository, PR checks are processed one after another in a FIFO (First-In-First-Out) manner. This prevents git conflicts and cache contention within a single repository.
• Parallel across Repos: Checks for different repositories (e.g., Repo A and Repo B) run in parallel, as they are managed by independent RepoQueue instances.

Workflow

1. Request Arrival: A webhook triggers an Enqueue operation via the QueueManager.
2. Queue Management: The QueueManager looks up the existing queue for the repository's URL or creates a new RepoQueue on-demand.
3. Worker Processing: Each RepoQueue maintains a single worker goroutine that pulls requests from a buffered channel and processes them one by one.
4. Shutdown: During a graceful shutdown, the system stops accepting new requests, allows in-flight work to finish, and notifies users of any dropped requests via PR comments.

                    Webhook Arrives
                         |
                         v
                  ┌──────────────┐
                  │ QueueManager │
                  │   (Global)   │
                  └──────┬───────┘
                         |
              Lookup or Create Queue
                         |
        ┌────────────────┼────────────────┐
        v                v                v
   ┌─────────┐      ┌─────────┐     ┌─────────┐
   │ Queue A │      │ Queue B │     │ Queue C │
   │ Repo A  │      │ Repo B  │     │ Repo C  │
   └────┬────┘      └────┬────┘     └────┬────┘
        │                │                │
   Buffered Chan   Buffered Chan   Buffered Chan
   [PR3, PR2]       [PR5]           [PR7]
        │                │                │
        v                v                v
   ┌─────────┐      ┌─────────┐     ┌─────────┐
   │Worker A │      │Worker B │     │Worker C │
   │(1 goro) │      │(1 goro) │     │(1 goro) │
   └─────────┘      └─────────┘     └─────────┘
   Sequential       Sequential      Sequential
   Processing       Processing       Processing

The local development environment is powered by Tilt.dev. Tilt manages the building, testing, and running of kubechecks within a local Kubernetes cluster. It also handles deploying ArgoCD, demo applications, and ngrok for webhook testing.

1. Store secrets in your OS keychain

It is highly recommended to store secrets in your OS keychain rather than using a .secret file to avoid keeping plaintext on disk.

Required: You must provide either GITLAB_TOKEN or GITHUB_TOKEN. Optional: KUBECHECKS_WEBHOOK_SECRET, OPENAI_API_TOKEN, or ANTHROPIC_API_KEY.

macOS (Keychain Access): Use the security command. Use the -w flag without a value to prompt for the secret interactively, which prevents the secret from appearing in your shell history.

Linux (pass): Install pass (e.g., sudo apt install pass), initialize it with your GPG key using pass init "your-email@example.com", and then use pass insert to add secrets.

2. Configure VCS type

If testing with GitHub, create a tilt_config.json file in the root directory to specify the version control system (the default is gitlab).

3. Start Tilt

Run tilt up from the root directory of the repository. You can then press the space bar in the terminal to open the Tilt web UI.

// tilt_config.json
{
    "vcs-type": "github"
}