Kubeshop Triggers API

openapi: 3.0.1
info:
  title: Testkube Standalone Agent api Triggers API
  description: API for Testkube Standalone Agent
  contact:
    email: info@testkube.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 1.0.0
servers:
- url: https://api.testkube.io
  description: Testkube Cloud Control Plane API Endpoint
- url: https://<your-testkube-api-host>
  description: Testkube On-Prem API Endpoint
tags:
- name: Triggers
paths:
  /triggers:
    get:
      parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/Selector'
      summary: List test triggers
      description: List test triggers from the kubernetes cluster
      operationId: listTestTriggers
      responses:
        '200':
          description: successful list operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TestTrigger'
            text/yaml:
              schema:
                type: string
        '400':
          description: problem with selector parsing - probably some bad input occurs
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        '502':
          description: problem communicating with kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
      tags:
      - Triggers
    post:
      summary: Create new test trigger
      description: Create new test trigger CRD inside a Kubernetes cluster
      operationId: createTestTrigger
      requestBody:
        description: test trigger body
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestTriggerUpsertRequest'
          text/yaml:
            schema:
              type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestTrigger'
            text/yaml:
              schema:
                type: string
        '400':
          description: problem with test trigger definition - probably some bad input occurs (invalid JSON body or similar)
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        '502':
          description: problem communicating with kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
      tags:
      - Triggers
    patch:
      summary: Bulk update test triggers
      description: Updates test triggers provided as an array in the request body
      operationId: bulkUpdateTestTriggers
      requestBody:
        description: array of test trigger upsert requests
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TestTriggerUpsertRequest'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TestTrigger'
        '400':
          description: problem with test trigger definition - probably some bad input occurs (invalid JSON body or similar)
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        '502':
          description: problem communicating with kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
      tags:
      - Triggers
    delete:
      summary: Delete test triggers
      description: Deletes all or labeled test triggers
      operationId: deleteTestTriggers
      parameters:
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/Selector'
      responses:
        '204':
          description: no content
        '400':
          description: problem with selector parsing - probably some bad input occurs
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        '404':
          description: test trigger not found
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        '502':
          description: problem communicating with kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
      tags:
      - Triggers
  /triggers/{id}:
    get:
      parameters:
      - $ref: '#/components/parameters/ID'
      - $ref: '#/components/parameters/Namespace'
      summary: Get test trigger by ID
      description: Get test trigger by ID from CRD in kubernetes cluster
      operationId: getTestTriggerByID
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestTrigger'
            text/yaml:
              schema:
                type: string
        '404':
          description: test trigger not found
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        '502':
          description: problem communicating with kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
      tags:
      - Triggers
    patch:
      parameters:
      - $ref: '#/components/parameters/ID'
      - $ref: '#/components/parameters/Namespace'
      - name: mode
        in: query
        description: "Update mode for the trigger. When set to \"replace\", the entire trigger \nis replaced with the request body (full replacement semantics). When not \nset or set to any other value, merge semantics are used where only \nnon-null fields from the request are applied to the existing trigger.\nThis is used by cloud-api to signal that the original request was YAML.\n"
        required: false
        schema:
          type: string
          enum:
          - replace
      summary: Update test trigger
      description: Update test trigger
      operationId: updateTestTrigger
      requestBody:
        description: test trigger upsert request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestTriggerUpsertRequest'
          text/yaml:
            schema:
              type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestTrigger'
        '400':
          description: problem with test trigger definition - probably some bad input occurs (invalid JSON body or similar)
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        '404':
          description: test trigger not found
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        '502':
          description: problem communicating with kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
      tags:
      - Triggers
    delete:
      parameters:
      - $ref: '#/components/parameters/ID'
      - $ref: '#/components/parameters/Namespace'
      summary: Delete test trigger
      description: Deletes a test trigger
      operationId: deleteTestTrigger
      responses:
        '204':
          description: no content
        '404':
          description: test trigger not found
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
        '502':
          description: problem communicating with kubernetes cluster
          content:
            application/problem+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Problem'
      tags:
      - Triggers
components:
  schemas:
    Syncable:
      description: 'source information about resources that may have been synced from multiple sources.

        An empty source indicates that the source was the UI/API for backwards compatibility.

        '
      type: object
      properties:
        creationSource:
          description: the original source from which the resource was created
          $ref: '#/components/schemas/Source'
        lastModificationSource:
          description: the source from which the last modification of the resource originated
          $ref: '#/components/schemas/Source'
    TestTriggerConcurrencyPolicies:
      description: supported concurrency policies for test triggers
      type: string
      enum:
      - allow
      - forbid
      - replace
    TestTriggerProbe:
      description: supported probe for test triggers
      type: object
      properties:
        scheme:
          type: string
          description: test trigger condition probe scheme to connect to host, default is http
          example: http
        host:
          type: string
          description: test trigger condition probe host, default is pod ip or service name
          example: testkube-api-server
        path:
          type: string
          description: test trigger condition probe path to check, default is /
          example: /
        port:
          type: integer
          format: int32
          description: test trigger condition probe port to connect
          example: 80
        headers:
          type: object
          description: test trigger condition probe headers to submit
          additionalProperties:
            type: string
          example:
            Content-Type: application/xml
    TestTriggerUpsertRequest:
      description: test trigger create or update request body
      type: object
      required:
      - event
      - action
      - execution
      - testSelector
      allOf:
      - $ref: '#/components/schemas/TestTrigger'
      - $ref: '#/components/schemas/ObjectRef'
    TestTriggerContentGitPullRequest:
      type: object
      description: Pull request trigger configuration for GitHub API polling.
      properties:
        types:
          type: array
          description: PR activity types to watch (e.g. "opened", "synchronize", "reopened", "closed"). If empty, all types are watched.
          items:
            type: string
        branches:
          type: array
          description: Base branch name patterns to watch (glob supported). If empty, PRs targeting any base branch are watched.
          items:
            type: string
        branchesIgnore:
          type: array
          description: Base branch name patterns to exclude (glob supported). Takes precedence over branches.
          items:
            type: string
    TestTriggerResources:
      description: supported kubernetes resources for test triggers
      type: string
      enum:
      - pod
      - deployment
      - statefulset
      - daemonset
      - service
      - ingress
      - event
      - configmap
      - content
    TestTriggerFieldOperator:
      type: string
      description: supported comparison operators for TestTrigger match conditions
      enum:
      - equals
      - not_equals
      - exists
      - not_exists
      - changed
      - changed_to
      - changed_from
    TestTriggerSelector:
      type: object
      properties:
        name:
          type: string
          description: kubernetes resource name selector
          example: nginx
        nameRegex:
          type: string
          description: kubernetes resource name regex
          example: nginx.*
        namespace:
          type: string
          description: resource namespace
          example: testkube
        namespaceRegex:
          type: string
          description: kubernetes resource namespace regex
          example: test*
        labelSelector:
          $ref: https://raw.githubusercontent.com/garethr/kubernetes-json-schema/master/v1.7.8/_definitions.json#/definitions/io.k8s.apimachinery.pkg.apis.meta.v1.LabelSelector
          description: label selector for Kubernetes resources
    TestTriggerProbeSpec:
      type: object
      properties:
        probes:
          type: array
          items:
            $ref: '#/components/schemas/TestTriggerProbe'
          description: list of test trigger probes
        timeout:
          type: integer
          format: int32
          description: duration in seconds the test trigger waits for probes, until its stopped
          example: 1
        delay:
          type: integer
          format: int32
          description: duration in seconds the test trigger waits between probes
          example: 1
    TestTriggerContentSelector:
      type: object
      properties:
        git:
          $ref: '#/components/schemas/TestTriggerContentGit'
    TestTriggerFieldCondition:
      type: object
      required:
      - path
      - operator
      properties:
        path:
          type: string
          description: Dot-path to the field in the watched resource, e.g. ".spec.replicas".
        operator:
          $ref: '#/components/schemas/TestTriggerFieldOperator'
        value:
          type: string
          description: Value to compare against for value-based operators.
    TestTriggerConditionSpec:
      type: object
      properties:
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/TestTriggerCondition'
          description: list of test trigger conditions
        timeout:
          type: integer
          format: int32
          description: duration in seconds the test trigger waits for conditions, until its stopped
          example: 1
        delay:
          type: integer
          format: int32
          description: duration in seconds the test trigger waits between condition checks
          example: 1
    ExecutionTarget:
      type: object
      properties:
        match:
          type: object
          description: runner labels to match
          additionalProperties:
            type: array
            items:
              type: string
        not:
          type: object
          description: runner labels to NOT match
          additionalProperties:
            type: array
            items:
              type: string
        replicate:
          type: array
          description: list of runner labels to replicate the executions
          items:
            type: string
    TestWorkflowTagValue:
      type: object
      description: tag values to pass to the test workflow execution
      additionalProperties:
        type: string
    FieldRef:
      type: object
      required:
      - fieldPath
      description: 'Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels[''<KEY>'']`, `metadata.annotations[''<KEY>'']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs.'
      properties:
        apiVersion:
          description: Version of the schema the FieldPath is written in terms of, defaults to "v1".
          type: string
        fieldPath:
          description: Path of the field to select in the specified API version.
          type: string
    TestWorkflowConfigValue:
      type: object
      description: configuration values to pass to the template
      additionalProperties:
        type: string
    Source:
      description: synchronisation sources
      type: string
      enum:
      - kubernetes
    TestTriggerActions:
      description: supported actions for test triggers
      type: string
      enum:
      - run
    TestTrigger:
      type: object
      required:
      - event
      - action
      - execution
      - testSelector
      properties:
        name:
          type: string
          description: test trigger name
          example: test1
        namespace:
          type: string
          description: test trigger namespace
          example: testkube
        labels:
          type: object
          description: test trigger labels
          additionalProperties:
            type: string
          example:
            env: prod
            app: backend
        annotations:
          type: object
          description: test trigger annotations
          additionalProperties:
            type: string
          example:
            group: teamA
            app: backend
        selector:
          $ref: https://raw.githubusercontent.com/garethr/kubernetes-json-schema/master/v1.7.8/_definitions.json#/definitions/io.k8s.apimachinery.pkg.apis.meta.v1.LabelSelector
          description: label selector for events
        resource:
          $ref: '#/components/schemas/TestTriggerResources'
        resourceRef:
          $ref: '#/components/schemas/TestTriggerResourceRef'
        resourceSelector:
          $ref: '#/components/schemas/TestTriggerSelector'
        event:
          type: string
          description: listen for event for selected resource
          example: modified
        match:
          type: array
          description: Match filters which object changes fire the trigger (ANDed).
          items:
            $ref: '#/components/schemas/TestTriggerFieldCondition'
        listener:
          description: 'Selects which listener agent(s) watch the cluster and fire this

            trigger, using the same match selector as the action target (e.g.

            match.id). Empty means broadcast (every listener fires). Required

            when match is set: schema-aware validation runs against a specific

            listener''s cluster-resources snapshot.

            '
          $ref: '#/components/schemas/ExecutionTarget'
        conditionSpec:
          $ref: '#/components/schemas/TestTriggerConditionSpec'
        probeSpec:
          $ref: '#/components/schemas/TestTriggerProbeSpec'
        contentSelector:
          $ref: '#/components/schemas/TestTriggerContentSelector'
        action:
          $ref: '#/components/schemas/TestTriggerActions'
        actionParameters:
          $ref: '#/components/schemas/TestTriggerActionParameters'
        execution:
          $ref: '#/components/schemas/TestTriggerExecutions'
        testSelector:
          $ref: '#/components/schemas/TestTriggerSelector'
        concurrencyPolicy:
          $ref: '#/components/schemas/TestTriggerConcurrencyPolicies'
        disabled:
          type: boolean
          description: whether test trigger is disabled
          default: false
          example:
          - true
          - false
        sync:
          $ref: '#/components/schemas/Syncable'
    TestTriggerResourceRef:
      type: object
      required:
      - kind
      properties:
        group:
          type: string
          description: Group is the API group (empty for core resources like Pod, Service).
          example: apps
        version:
          type: string
          description: Version is the API version.
          example: v1
        kind:
          type: string
          description: Kind is the resource kind.
          example: Deployment
    Problem:
      description: problem response in case of error
      type: object
      properties:
        type:
          type: string
          description: Type contains a URI that identifies the problem type.
          example: https://kubeshop.io/testkube/problems/invalidtestname
        title:
          type: string
          description: Title is a short, human-readable summary of the problem type. This title SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
          example: Invalid test name
        status:
          type: integer
          description: HTTP status code for this occurrence of the problem.
          example: 500
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          example: Your test name can't contain forbidden characters like "}}}" passed
        instance:
          type: string
          description: A URI that identifies the specific occurrence of the problem. This URI may or may not yield further information if de-referenced.
          example: http://10.23.23.123:8088/tests
    TestTriggerConditionStatuses:
      description: supported kubernetes condition statuses for test triggers
      type: string
      enum:
      - 'True'
      - 'False'
      - Unknown
    ObjectRef:
      required:
      - name
      type: object
      properties:
        namespace:
          type: string
          description: object kubernetes namespace
          example: testkube
        name:
          type: string
          description: object name
          example: name
    TestTriggerCondition:
      description: supported condition for test triggers
      type: object
      required:
      - status
      - type
      properties:
        status:
          $ref: '#/components/schemas/TestTriggerConditionStatuses'
        type:
          type: string
          description: test trigger condition
          example: Progressing
        reason:
          type: string
          description: test trigger condition reason
          example: NewReplicaSetAvailable
        ttl:
          type: integer
          format: int32
          description: duration in seconds in the past from current time when the condition is still valid
          example: 1
    TestTriggerContentGit:
      type: object
      required:
      - uri
      properties:
        uri:
          type: string
          description: URI of the git repository to watch.
        branches:
          type: array
          description: Branch name patterns to watch (glob supported, e.g. "main", "release/*"). If empty, all branches are watched.
          items:
            type: string
        branchesIgnore:
          type: array
          description: Branch name patterns to exclude (glob supported). Takes precedence over branches.
          items:
            type: string
        paths:
          type: array
          description: paths to watch for changes (glob supported)
          items:
            type: string
        pathsIgnore:
          type: array
          description: Path patterns to exclude (glob supported). Takes precedence over paths.
          items:
            type: string
        tags:
          type: array
          description: Tag name patterns to watch (glob supported, e.g. "v*", "v1.*").
          items:
            type: string
        tagsIgnore:
          type: array
          description: Tag name patterns to exclude (glob supported). Takes precedence over tags.
          items:
            type: string
        username:
          type: string
          description: plain text username to fetch with
        usernameFrom:
          $ref: '#/components/schemas/EnvVarSource'
        token:
          type: string
          description: 'plain text token to fetch with. Warning: this credential is stored in plain text in the trigger spec; prefer tokenFrom instead.'
        tokenFrom:
          $ref: '#/components/schemas/EnvVarSource'
        sshKey:
          type: string
          description: 'plain text SSH private key to fetch with. Warning: this credential is stored in plain text in the trigger spec; prefer sshKeyFrom instead.'
        sshKeyFrom:
          $ref: '#/components/schemas/EnvVarSource'
        authType:
          type: string
          enum:
          - basic
          - header
        pullRequest:
          $ref: '#/components/schemas/TestTriggerContentGitPullRequest'
    ResourceFieldRef:
      type: object
      required:
      - resource
      description: 'Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported.'
      properties:
        containerName:
          description: 'Container name: required for volumes, optional for env vars'
          type: string
        divisor:
          type: string
          pattern: ^[0-9]+(m|[GMK]i)$
        resource:
          description: 'Required: resource to select'
          type: string
    EnvVarSource:
      type: object
      description: EnvVarSource represents a source for the value of an EnvVar.
      properties:
        configMapKeyRef:
          type: object
          required:
          - key
          description: Selects a key of a ConfigMap.
          properties:
            key:
              description: The key to select.
              type: string
            name:
              description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid?'
              type: string
            optional:
              nullable: true
              description: Specify whether the ConfigMap or its key must be defined
              type: boolean
        fieldRef:
          $ref: '#/components/schemas/FieldRef'
        resourceFieldRef:
          $ref: '#/components/schemas/ResourceFieldRef'
        secretKeyRef:
          type: object
          required:
          - key
          description: Selects a key of a secret in the pod's namespace
          properties:
            key:
              description: The key of the secret to select from.  Must be a valid secret key.
              type: string
            name:
              description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid?'
              type: string
            optional:
              nullable: true
              description: Specify whether the Secret or its key must be defined
              type: boolean
    TestTriggerActionParameters:
      description: supported action parameters for test triggers
      type: object
      properties:
        config:
          $ref: '#/components/schemas/TestWorkflowConfigValue'
        tags:
          $ref: '#/components/schemas/TestWorkflowTagValue'
        target:
          $ref: '#/components/schemas/ExecutionTarget'
    TestTriggerExecutions:
      description: supported test resources for test triggers
      type: string
      enum:
      - test
      - testsuite
      - testworkflow
  parameters:
    Namespace:
      in: query
      name: namespace
      schema:
        type: string
        default: testkube
        description: Namespace of the object
    Selector:
      in: query
      name: selector
      schema:
        type: string
        description: Labels to filter by
    ID:
      in: path
      name: id
      schema:
        type: string
      required: true
      description: unique id of the object