feat: add OCI artifact support for testworkflows

[dhimanAbhi]

Pull request description

This PR introduces support for OCI registry sources in the container executor. It enables fetching test assets directly from OCI-compliant registries (such as Docker Hub, GHCR, or self-hosted registries) as an alternative to Git-based sources. This addition provides a secure and reliable way to distribute test content, especially for air-gapped or restricted network environments, here access to public Git repositories may not be feasible.

It solves issue #4849

Proof Manifests

These are logs of testworkflow execution where I had pushed cypress test defined in testkube/test/cypress/cypress-12 to my dockerhub private repo as an artifact using ORAS. This PR fetches the content just like fetching from Git Source.

$ testkube watch twe 68f37d47a1ceb4408c389b79

Context:  (999.0.0-5d710d124)   Namespace: testkube
---------------------------------------------------
parsing server version 'dev': Invalid Semantic Version
Test Workflow Execution:
Name:                 oci-test
Execution ID:         68f37d47a1ceb4408c389b79
Execution name:       oci-test-1
Execution namespace:
Execution number:     1
Requested at:         2025-10-18 11:43:03.454 +0000 UTC
Disabled webhooks:    false
Status:               running
Queued at:            2025-10-18 11:43:03.454 +0000 UTC
Started at:           2025-10-18 11:43:03.454 +0000 UTC

Getting logs from test workflow job 68f37d47a1ceb4408c389b79
(SuccessfulCreate) Created pod: 68f37d47a1ceb4408c389b79-h27ns
(Scheduled) Successfully assigned testkube/68f37d47a1ceb4408c389b79-h27ns to minikube
(Pulled) Container image "docker.io/testworkflow-toolkit:oci" already present on machine
Creating state... done
Initializing state... done
Configuring init process... skipped
Configuring toolkit... done
Configuring shell... skipped

• passed in 2.613s

• (1/2) Get OCI artifact
Starting OCI fetch for artifact: abhi2002dhiman/cypress-test-artifact:latest to path: /data/repo
Downloading and extracting artifact...
✅ OCI artifact fetched successfully.
Moving artifact contents to /data/repo...
📥 Moving the contents to /data/repo...
📥 Adjusting access permissions...
🔎 Destination folder contains following files ...
/data/repo
/data/repo/.gitignore
/data/repo/Dockerfile
/data/repo/cypress
/data/repo/cypress/e2e
/data/repo/cypress/e2e/smoke.cy.js
/data/repo/cypress/e2e/smoke2.cy.js
/data/repo/cypress/fixtures
/data/repo/cypress/fixtures/.gitkeep
/data/repo/cypress/support
/data/repo/cypress/support/.gitkeep
/data/repo/cypress/support/e2e.js
/data/repo/cypress.config.js
/data/repo/package-lock.json
/data/repo/package.json
✅ Successfully fetched OCI artifact: abhi2002dhiman/cypress-test-artifact:latest

• passed in 2.603s
(Pulled) Container image "docker.io/testworkflow-toolkit:oci" already present on machine

• (2/2) Run shell command
/data/repo
├── Dockerfile
├── cypress
│   ├── e2e
│   │   ├── smoke.cy.js
│   │   └── smoke2.cy.js
│   ├── fixtures
│   └── support
│       └── e2e.js
├── cypress.config.js
├── package-lock.json
└── package.json2025-10-18T11:43:09.086320526Z 4 directories, 7 files

Testworkflow Definition

Users can define an OCI registry source specifying:

• registry — where the artifact is hosted
• image — artifact name and tag
• path — path within the artifact to the test directory
• username and token — optional, for private registries

Template -

apiVersion: testworkflows.testkube.io/v1
kind: TestWorkflow
metadata:
  name: oci-example
spec:
  content:
    oci:
      registry: "<registry_name>"
      image: "<artifact_name_with_tag>"
      path: "<path_to_test>"
      username: "<username>"
      token: "<token_or_password>"
  steps:
    - shell: "tree /data/repo"

Example

apiVersion: testworkflows.testkube.io/v1
kind: TestWorkflow
metadata:
  name: oci-example
spec:
  content:
    oci:
      registry: "docker.io"
      image: "abhi2002dhiman/cypress-test-artifact:latest"
      path: "."
      username: "abhi2002dhiman"
      token: "my_token"
  steps:
    - shell: "tree /data/repo"

Checklist (choose whats happened)

• breaking change! (describe)
• tested locally
• tested on cluster
• added new dependencies
• updated the docs
• added a test

Breaking changes

Changes

Fixes

[vsukhin]

hey, @dhimanAbhi thank you for your contribution. Looks like a good work, but there is no api spec changes there, that is sued to generate models

[vsukhin]

add api spec changes used for mode generation

[vsukhin]

https://github.com/kubeshop/testkube/blob/main/api/v1/testkube.yaml

[dhimanAbhi]

Thanks @vsukhin , I updated api spec and some minor improvements. Let me know if you have any other thoughts or suggestions for further changes!

[vsukhin]

I have one questions,are CRD installed without kubectl apply --server-side having thier size was increased?

[vsukhin]

Also, don't you mind to prepare PR for https://github.com/kubeshop/testkube-docs with updated Content spec?

[dhimanAbhi]

I have one questions,are CRD installed without kubectl apply --server-side having thier size was increased?

@vsukhin , I generated CRDs and api spec using Makefile commands make generate-openapi and and make generate-crds . If there’s another recommended way to generate CRDs, please let me know, I’ll update it right away!

[dhimanAbhi]

Also, don't you mind to prepare PR for https://github.com/kubeshop/testkube-docs with updated Content spec?

Definetly. I will soon make a PR for the documentation update.

[vsukhin]

I have one questions,are CRD installed without kubectl apply --server-side having thier size was increased?

@vsukhin , I generated CRDs and api spec using Makefile commands make generate-openapi and and make generate-crds . If there’s another recommended way to generate CRDs, please let me know, I’ll update it right away!

It's fine. It's just about testing, because for large CRDs we can have a warning from Kubernetes about thier size

[dhimanAbhi]

I have one questions,are CRD installed without kubectl apply --server-side having thier size was increased?

@vsukhin , I generated CRDs and api spec using Makefile commands make generate-openapi and and make generate-crds . If there’s another recommended way to generate CRDs, please let me know, I’ll update it right away!

It's fine. It's just about testing, because for large CRDs we can have a warning from Kubernetes about thier size

Sounds Great. Let me know if anything else is required from my end! 🙌