Version: Next

ComponentWorkflow

A ComponentWorkflow is a platform engineer-defined template specifically designed for building components in OpenChoreo. ComponentWorkflows enforce a structured schema for repository information while providing flexibility for additional build configuration. This enables powerful build-specific platform features like auto-builds, webhooks, build traceability, and monorepo support.

API Version

openchoreo.dev/v1alpha1

Resource Definition

Metadata

ComponentWorkflows are namespace-scoped resources.

apiVersion: openchoreo.dev/v1alpha1
kind: ComponentWorkflow
metadata:
  name: <componentworkflow-name>
  namespace: <namespace>  # Namespace for grouping component workflows

Spec Fields

Field	Type	Required	Default	Description
`schema`	ComponentWorkflowSchema	Yes	-	Parameter schemas including required system parameters and flexible developer parameters
`runTemplate`	object	Yes	-	Kubernetes resource template (typically Argo Workflow) with CEL expressions for runtime evaluation
`resources`	[]ComponentWorkflowResource	No	-	Additional Kubernetes resources to be created alongside the workflow (e.g., ExternalSecrets, ConfigMaps)

Schema

The schema field defines parameter schemas for the ComponentWorkflow:

Field	Type	Required	Default	Description
`types`	object	No	-	Reusable type definitions that can be referenced in schema fields
`systemParameters`	object	Yes	-	Required structured schema for repository information
`parameters`	object	No	-	Flexible PE-defined schema for additional build configuration

System Parameters Schema (Required)

System parameters follow a fixed structure required for build-specific platform features. Platform engineers can customize defaults, enums, and descriptions, but must maintain the field structure.

Required Structure:

schema:
  systemParameters:
    repository:
      url: 'string | description="Git repository URL"'
      secretRef: 'string | description="SecretReference name for private repo auth (optional)"'
      revision:
        branch: 'string | default=main description="Git branch"'
        commit: 'string | description="Commit SHA (optional)"'
      appPath: 'string | default=. description="Application path"'

Field Constraints:

Field names must match exactly: url, secretRef, revision.branch, revision.commit, appPath
All fields must be of type string
Platform Engineers can customize: defaults, enums, descriptions, validation rules
Platform Engineers cannot change: field names, nesting structure, or types

Private Repository Access:

The secretRef field is optional and used for authenticating with private Git repositories:

References a SecretReference CR in the same namespace
SecretReference maps to credentials in external secret stores (Vault, AWS Secrets Manager, etc.)
During workflow execution, credentials are synced to the build plane via ExternalSecrets
Enables secure access without storing credentials in the control plane

Developer Parameters Schema (Flexible)

Developer parameters provide complete freedom for platform engineers to define additional build configuration using the same inline type definition syntax as ComponentType:

"type | default=value enum=val1,val2 minimum=N maximum=N"

Supported types: string, integer, boolean, array<type>, nested objects

Example:

schema:
  parameters:
    version: integer | default=1 description="Build version"
    testMode: string | enum=unit,integration,none default=unit
    resources:
      cpuCores: integer | default=1 minimum=1 maximum=8
      memoryGb: integer | default=2 minimum=1 maximum=32
    cache:
      enabled: boolean | default=true
      paths: '[]string | default=["/root/.cache"]'

Types (Optional Reusable Type Definitions)

The optional types field allows platform engineers to define reusable type definitions that can be referenced in the parameter schema, similar to ComponentType:

schema:
  types:
    Endpoint:
      name: string
      port: integer
      type: string | enum=REST,HTTP,TCP,UDP
    ResourceLimit:
      cpu: string | default=1000m
      memory: string | default=1Gi

  parameters:
    endpoints: '[]Endpoint | default=[]'
    limits: ResourceLimit
    buildArgs: '[]string | default=[]'

CEL Variables in Run Templates

ComponentWorkflow run templates support CEL expressions with access to:

Variable	Description
`${metadata.workflowRunName}`	ComponentWorkflowRun CR name (the execution instance)
`${metadata.componentName}`	Component name
`${metadata.projectName}`	Project name
`${metadata.orgName}`	Organization name (namespace)
`${systemParameters.*}`	Repository information from system parameters
`${parameters.*}`	Developer-provided values from the flexible parameter schema
`${secretRef.*}`	SecretReference data (available when `secretRef` is provided)

Secret Reference Variables:

When systemParameters.repository.secretRef is provided:

${secretRef.type} - Secret type (kubernetes.io/basic-auth, kubernetes.io/ssh-auth)
${secretRef.data} - Array of secret data mappings from SecretReference
Used in conditional resources with includeWhen: ${has(systemParameters.repository.secretRef)}