GitHub
The GitHub integration connects a GitHub repository to a Testkube environment so PR activity runs your Test Workflows and results post back on the PR as check-runs.
Requires both the Control Plane and the Runner on version 2.13.1 or later. Older runners can render incomplete data in the Running Context and the Resource Usage chart of child executions triggered through the integration.
Available on Testkube Cloud and on-prem Control Plane. On-prem requires the GitHub integration enabled in the Helm chart and a GitHub App configured against the target organization. See Using GitHub Apps with Testkube.

What it does
For every event received from GitHub, the integration:
- Matches the event to your configured integration.
- Runs the Workflows selected for the repository against the commit that produced the event.
- Posts execution status back to the PR (check-run) or commit (status).
Workflows that run can be:
- Existing Workflows already in the environment, attached when the repository is connected.
- Auto-generated Workflows materialized from frameworks detected in the repo (Playwright, Cypress, k6, Postman, JMeter, Maven, Gradle, Go, Node).
Prerequisites
- A Testkube environment with a runner connected. See Runners Overview.
- On on-prem, the GitHub integration enabled in
values.yaml. - The Testkube GitHub App installed on the target repository.
- The user connecting the repository must have
adminaccess to it. - If the GitHub organization uses an IP allow list, allow the Cloud Control Plane's outbound addresses.
Installing the GitHub App
On Testkube Cloud, open Integrations > Git Integration and click Connect my first repository. GitHub asks which organization and which repos the App may access.


On on-prem, the operator creates the App during deployment. See Using GitHub Apps with Testkube.
Required App permissions:
- Contents: read
- Metadata: read
- Pull requests: read & write
- Checks: read & write
- Issues: read (for the
@testkubecomment trigger)
Connecting a repository
From the dashboard, open Integrations > Git Integration > Connect repository:
- Pick the org and repo (only repos the App is installed on show up).
- Choose what runs against it:
- Attach existing Workflows already in this environment, or
- Scan the repo and let Testkube propose a starting point based on the detected stack (Playwright, Cypress, k6, Postman, JMeter, Maven, Gradle, Go, Node). Detection is best-effort, review and adjust the proposed set before confirming.
- Confirm. Testkube persists the selection, materializes one auto-gen Workflow per selected framework (for the scan path), and starts receiving webhook events.


What triggers a run
| Event | Action | Notes |
|---|---|---|
pull_request | opened | draft == false |
pull_request | ready_for_review | |
pull_request | synchronize | new commit pushed to the PR head |
issue_comment | created on a PR | body must mention @testkube (editing a comment does not count) |
push | branches matched by config | |
tag push | tag globs matched by config | |
release | published / prereleased | prereleases opt-in |
Toggle event types per integration from the dashboard configuration panel.

Configuration
Every integration has a Configuration panel that controls PR feedback, AI analysis, and merge gating.
Pull request feedback
Chooses how the PR comment looks:
- Condensed (default): title, brief pass/fail, collapsible executed Workflows, a short collapsible AI analysis, and a link back to the dashboard.
- Detailed: everything in Condensed, plus a pipeline phase breakdown and a longer collapsible AI analysis section.


GitHub Checks
- Block pull requests when executions fail: when on, a failed required Workflow marks the aggregate check-run as failed and blocks merge (if branch protection requires the check to pass). Off means the check-run still reports the result, but does not block.

AI Summary
Adds an AI-generated execution summary to the PR comment.
- Enable AI analysis on pull requests: master toggle for the block.
- Agent: the AI agent that produces the summary. Only agents available in the environment show up. Analysis runs with nobody present, so AI agents that sign in to an MCP Server as each person can't be picked. If the chosen agent is later changed to sign in that way, analysis is skipped until it has a shared key or another agent is picked.
- Model: model used by the agent. Leave on Platform default unless you need to pin a specific one.
- Run when:
- On fail or abort: only run the summary when the execution does not pass, useful for keeping AI cost tied to real signal.
- Always: run after every execution on a PR.

AI sessions
When AI Summary is on, Testkube creates one AI session per pull request. It is the assistant conversation that produces the AI Analysis block posted on the PR comment.
- One session per PR. Every subsequent push to the PR appends into the same session, so context builds up as the PR evolves rather than being lost between commits.
- Where to open it:
- From the PR comment, click Continue analysis in Testkube at the bottom of the AI Analysis block.
- From the dashboard, open the integration's GitHub events tab. Events whose analysis produced a session show a View chat link in the AI Session column.
- Both entry points land on the same conversation under the environment's Chats section. From there you can keep asking follow-ups, inspect the assistant's reasoning, or dig into the tool calls it made against your executions.

Auto-generated Workflows

Every auto-gen Workflow is labelled so the GitHub integration can reconcile it:
| Label / Annotation | Value |
|---|---|
testkube.io/git-integration-integration-id | ID of the owning integration |
testkube.io/git-integration-framework | Detected framework (e.g. playwright) |
testkube.io/git-integration-provider | github |
testkube.io/git-integration-managed (annotation) | set to "false" to detach |
testkube.io/managed-by | git-integration |
Detaching a generated Workflow
Add testkube.io/git-integration-managed: "false" as an annotation on the Workflow to opt it out of reconcile:
- Testkube no longer overwrites your edits on rescan.
- The Workflow is not deleted when the integration is removed.
- It keeps running on every triggering event until you remove it from the integration selection.
Re-set the annotation to "true" (or remove it) to bring the Workflow back under management.
Event parameters available to your Workflows
Declare the ones you need under spec.config:
| Key | Meaning |
|---|---|
PR_NUMBER | PR number. Empty on push/tag/release. |
PR_SHA | Head commit SHA of the PR. |
PR_BASE_REF | Base branch of the PR (e.g. main). |
PR_HEAD_REF | Head branch of the PR. |
PR_AUTHOR | GitHub login of the PR author. |
revision | Git ref for the event (commit SHA on push, refs/pull/<n>/head on PRs), consumed as-is by spec.content.git.revision so the clone step checks out the right commit. |
Workflows that do not declare these ignore them.
Filtering executions by the GitHub integration
Every execution scheduled by the GitHub integration carries actor.type = gitintegration. The Executions page has a Git Integration filter chip that returns those runs.

Re-scanning a repository
Framework detection is refreshed automatically when a PR event touches a stack anchor: go.mod, package.json, pom.xml, build.gradle, build.gradle.kts, Cargo.toml, requirements.txt, pyproject.toml, Pipfile, Gemfile, or composer.json. The GitHub integration re-runs detection on the PR head and updates the set of auto-gen Workflows before executing.
There is no dashboard button for a manual rescan today. To force one when needed, disconnect the integration and connect again; the connection flow re-runs detection.