Skip to main content
New to Testkube? Unleash the power of cloud native testing in Kubernetes with Testkube. Get Started >

Testkube GitHub Action

The Testkube GitHub Action installs Testkube and enables running any Testkube CLI command in a GitHub workflow. It is available on Github Marketplace. The action provides a flexible way to work with your pipeline and can be used with both commercial and open source deployments of Testkube.

Testkube​

How to configure Testkube CLI action for Testkube and Run a Test Workflow​

To use this GitHub Action for Testkube, you need to create an API token. Then, pass the organization and environment IDs, along with the token and other parameters specific for your use case.

If a Test Workflow is already created, you may directly run it using the command testkube run testworkflow TEST_WORKFLOW_NAME -f. However, if you need to create a Test Workflow in this workflow, please add a creation command, e.g.: testkube create testworkflow -f EXAMPLE_FILE.yaml.

steps:
  - uses: kubeshop/setup-testkube@v1
    with:
      organization: tkcorg_0123456789abcdef
      environment: tkcenv_fedcba9876543210
      token: tkcapi_0123456789abcdef0123456789abcd

  - run: |
      testkube run testworkflow TEST_WORKFLOW_NAME -f

It is recommended that sensitive values should never be stored as plaintext in workflow files, but rather as secrets. Secrets can be configured at the organization, repository, or environment level, and allow you to store sensitive information in GitHub.

steps:
  - uses: kubeshop/setup-testkube@v1
    with:
      organization: ${{ secrets.TkOrganization }}
      environment: ${{ secrets.TkEnvironment }}
      token: ${{ secrets.TkToken }}

  - run: |
      testkube run testworkflow TEST_WORKFLOW_NAME -f

Testkube Open Source​

How to Configure Testkube CLI Actions for Testkube Core OSS and Run a Test Workflow​

To connect to the self-hosted instance, you need to have kubectl configured for accessing your Kubernetes cluster, and simply passing optional namespace, if Testkube is not deployed in the default testkube namespace. You can also specify a particular Testkube CLI or API version (not to be confused with the Helm chart one). If the version is omitted, then the latest version is used. The list of [releases] (https://github.com/kubeshop/testkube/releases) can be found in the Testkube Github repository.

If a Test Workflow is already created, you may run it using the command testkube run testworkflow TEST_WORKFLOW_NAME -f. However, if you need to create a Test Workflow in this workflow, please add a creation command, e.g.: testkube create testworkflow -f EXAMPLE_FILE.yaml.

steps:
  - uses: kubeshop/setup-testkube@v1
    with:
      namespace: custom-testkube
      version: 2.0.11

  - run: |
      testkube run testworkflow TEST_WORKFLOW_NAME -f

Steps to connect to your Kubernetes cluster differ for each provider. You should check the docs of your Cloud provider on how to connect to the Kubernetes cluster from GitHub Action, or check examples in this documentation for selected providers.

How to Configure Testkube CLI Actions for Testkube Core OSS and Run a Test Workflow​

This workflow establishes a connection to EKS cluster and creates and runs a test using Testkube CLI. In this example, we also use GitHub secrets not to reveal sensitive data. Please make sure that the following points are satisfied:

  • The AwsAccessKeyId, AwsSecretAccessKeyId secrets should contain your AWS IAM keys with proper permissions to connect to EKS cluster.
  • The AwsRegion secret should contain an AWS region where EKS is.
  • Tke EksClusterName secret points to the name of EKS cluster you want to connect.
steps:
  - name: Checkout
    uses: actions/checkout@v4

  - uses: aws-actions/configure-aws-credentials@v4
    with:
      aws-access-key-id: ${{ secrets.aws-access-key }}
      aws-secret-access-key: ${{ secrets.aws-secret-access-key }}
      aws-region:  ${{ secrets.aws-region }}

  - run: |
      aws eks update-kubeconfig --name ${{ secrets.eks-cluster-name }} --region ${{ secrets.aws-region }}

  - uses: kubeshop/setup-testkube@v1
    -
  - run: |
      testkube run testworkflow TEST_WORKFLOW_NAME -f

How to Connect to GKE (Google Kubernetes Engine) Cluster and Run a Test Workflow​

This example connects to a k8s cluster in Google Cloud, creates and runs a Test Workflow using Testkube GH Action. Please make sure that the following points are satisfied:

  • The GKE Sevice Account should be created prior in Google Cloud and added to GH Secrets along with GKE Project value;
  • The GKE Cluster Name and GKE Zone can be added as environmental variables in the workflow.
steps:
  - name: Checkout
    uses: actions/checkout@v4

  - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5
    with:
      service_account_key: ${{ secrets.GKE_SA_KEY }}
      project_id: ${{ secrets.GKE_PROJECT }}

  - run: |-
      gcloud --quiet auth configure-docker

  - uses: google-github-actions/get-gke-credentials@db150f2cc60d1716e61922b832eae71d2a45938f
    with:
      cluster_name: ${{ env.GKE_CLUSTER_NAME }}
      location: ${{ env.GKE_ZONE }}
      credentials: ${{ secrets.GKE_SA_KEY }}

  - uses: kubeshop/setup-testkube@v1
  - run: |
      testkube run testworkflow TEST_WORKFLOW_NAME -f

Please consult the official documentation from GitHub on how to connect to GKE for more information here.

Complete Example of Working GitHub Actions Workflow and Testkube Tests Usage​

To integrate Testkube Github Actions into your workflow, please take a look at the example that sets up connection to GKE and creates and runs a Test Workflow:

name: Running Testkube Tests.
on:
  push:
    branches:
      - main
env:
  PROJECT_ID: ${{ secrets.GKE_PROJECT }}
  GKE_CLUSTER: cluster-1    # Add your cluster name here.
  GKE_ZONE: us-central1-c   # Add your cluster zone here.

jobs:
  setup-build-publish-deploy:
    name: Connect to GKE
    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v4

    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5
      with:
        service_account_key: ${{ secrets.GKE_SA_KEY }}
        project_id: ${{ secrets.GKE_PROJECT }}

    - run: |-
        gcloud --quiet auth configure-docker

    - uses: google-github-actions/get-gke-credentials@db150f2cc60d1716e61922b832eae71d2a45938f
      with:
        cluster_name: ${{ env.GKE_CLUSTER }}
        location: ${{ env.GKE_ZONE }}
        credentials: ${{ secrets.GKE_SA_KEY }}


      - uses: kubeshop/setup-testkube@v1
      - run: |
          testkube run testworkflow TEST_WORKFLOW_NAME -f

Using GitHub Apps with Testkube​

With GitHub Apps you can simplify authentication to cloning your GitHub repositories and more.

Configuration for single-tenant​

A GitHub App will be installed on the Testkube Deployment. This keeps configuration simple for most On Prem users which use a single organization.

Step-by-step Instructions​

First you create and install the GitHub App:

  1. Create a GitHub Apps using https://github.com/settings/apps/new. You could name it "Testkube for $YourOrg" if you are uncertain how to call it.
  2. Change repository permissions to enable read-access to "Content" and "Metadata".
  3. Generate a private key and download it.
  4. Install the GitHub App to your account through the GitHub website.
  5. Take the installation identifier from the URL.

Afterwards you configure Testkube during the Helm deployment:

  1. Create a Kubernetes Secret within the namespace of your Testkube Control Plane which contains your private key. You should check that you are in the correct namespace.
kubectl create secret generic testkube-github --from-file=key.pem=testkube-for-your-org.2025-02-03.private-key.pem
  1. Update your values.yaml to update the Control Plane's testkube-cloud-api sub-chart with your GitHub App details. Please make sure that your application and installation identifiers are strings or Helm's YAML parser might inadvertently change them to incorrect values.
testkube-cloud-api:
  api:
    github:
      appId: "your_application_id"
      privateKeyRef: "testkube-github"
      installationId: "your_installation_id"
  1. (Re)-Deploy Testkube
  2. You are now ready to use your GitHub App to clone your content!

Configuration for multi-tenancy​

This approach would install GitHub Apps on individual Testkube Organizations. The benefit is strict isolation across tenants.

This is not yet supported. Please reach out to us should you be interested in this functionality on Testkube Cloud Control Plane or should you need to separate installations within your On Prem deployment.