Syntax & Structure

KodeShift pipelines are defined as YAML files in a .kodeshift/ directory at the root of your Git repository. This guide covers every configuration option available.

Directory Structure

.kodeshift/
├── .kodeshift.yaml                  # Entry point — stages + includes
├── pipeline/
│   ├── .kodeshift-pipeline.yaml     # Job definitions
│   ├── .kodeshift-common.yaml       # Reusable script blocks
│   └── .kodeshift-trigger.yaml      # Webhook triggers + environment mapping
└── chart/                           # Helm chart for deployment
    ├── Chart.yaml
    ├── values.yaml                  # Base values
    ├── values-dev.yaml              # Dev overrides
    ├── values-staging.yaml          # Staging overrides
    └── values-prod.yaml             # Production overrides

When you initialize a pipeline through the UI, this entire structure is generated automatically on a dedicated kodeshift branch in your repository.

Main Configuration (`.kodeshift.yaml`)

The entry point defines which stages exist and which files to include.

stages:
  - gitleaks
  - analysis
  - build
  - deploy

includes:
  - pipeline/.kodeshift-pipeline.yaml
  - pipeline/.kodeshift-common.yaml
  - pipeline/.kodeshift-trigger.yaml

Fields

Field	Type	Description
`stages`	`list[string]` or `dict`	Ordered list of stage names (recommended), or legacy dict mapping environments to stage lists
`includes`	`list[string]`	Relative paths to included YAML files

Use the list format for stages. The dict format (stages: {dev: [...], qa: [...]}) is legacy and limits dynamic environment selection.

Job Definitions (`.kodeshift-pipeline.yaml`)

Each top-level key is a job name. The key must match one of the stages declared in .kodeshift.yaml.

build:
  stage: build
  image:
    name: shiftlabsdev/kaniko-executor:latest
    command:
      - /kaniko/executor
    args:
      - "--dockerfile=${DOCKERFILE}"
      - "--context=dir:///workspace/"
      - "--destination=${REGISTRY}/${REGISTRY_REPO}/${APP_NAME}:${ENV}-${IMAGE_TAG}"
    env:
      - name: DOCKER_CONFIG
        value: /kaniko/.docker
  script: []
  init:
    - "@clone_scripts"
  environments:
    - "*"
  allow_fail: true
  timeout: 600

Field Reference

Field	Type	Required	Default	Description
`stage`	string	yes	—	Must match a name in the `stages` list
`image`	object	yes	—	Container image configuration (see below)
`script`	list	yes	—	Main commands to execute
`init`	list	no	`[]`	Setup commands that run before `script`
`environments`	list	yes	—	Environment patterns this job applies to
`allow_fail`	bool or list	no	`false`	`true` for all envs, or a list of env names
`trigger`	string	no	`"auto"`	`"auto"` or `"manual"`
`timeout`	int	no	`600`	Max execution time in seconds
`parallel_execution`	bool	no	`false`	Run in parallel with other jobs in the same group
`stage_group`	string	no	null	Group name for parallel execution
`stage_group_order`	int	no	null	Execution order within the group
`job_name`	string	no	null	Display name in the UI

Both snake_case and camelCase field names are accepted (e.g. stage_group or stageGroup).

Image Configuration

Field	Type	Description
`name`	string	Container image (e.g. `shiftlabsdev/builder:latest`)
`command`	list	Override container entrypoint
`args`	list	Arguments passed to the entrypoint
`env`	list	Environment variables as `{name, value}` pairs

For standard jobs, only name is needed. The command, args, and env fields are used for specialized containers like Kaniko that require a custom entrypoint.

Script References

Scripts in init and script fields support several formats.

Reference syntax (`@`)

Reference a reusable block defined in .kodeshift-common.yaml:

init:
  - "@clone_scripts"
script:
  - "@security_scripts"

The legacy use_ prefix also works (use_clone_scripts) but @ is preferred.

Inline commands

script:
  - "echo 'Hello'"
  - |
    echo "Multiline"
    echo "Commands"

Advanced formats

Scripts can also be objects:

script:
  - command: "npm"
    args: ["run", "build"]
  - run: "echo done"
  - shell: "bash"
    command: "echo $SHELL"

Common Scripts (`.kodeshift-common.yaml`)

Define reusable script blocks that jobs reference with @:

clone_scripts:
  - "echo '--- Repository Clone ---'"
  - |
    git clone https://x-access-token:${GIT_TOKEN}@${GIT_REPO_URL} /workspace
  - "cd /workspace"
  - "git checkout ${BRANCH_CODE}"

security_scripts:
  - "cd /workspace"
  - |
    gitleaks detect \
      --source /workspace \
      --report-format json

Each key becomes a referenceable script name. Values are command lists following the same formats described above.

Environment Pattern Matching

The environments field on each job uses pattern matching to determine which environments a job runs in.

Pattern	Matches	Example
`*`	All environments	`["*"]`
`prod`	Exact match	`["prod"]`
`prod*`	Starts with	`["prod*"]` matches `prod`, `prod-eu`, `prod-us`
`*-eu`	Ends with	`["*-eu"]` matches `prod-eu`, `staging-eu`
`prod`	Contains	`["prod"]` matches `preprod`, `prod-eu`

Conditional allow_fail

allow_fail can be a list of environment names instead of a boolean:

analysis:
  allow_fail: ["dev", "qa"]    # Failures ignored in dev/qa, fatal in prod
  environments:
    - "*"

Trigger Configuration (`.kodeshift-trigger.yaml`)

Defines which Git events trigger the pipeline and how branches/tags map to environments.

on:
  push:
    branches:
      - develop
      - feature/*
      - feature/**
      - release/*
      - hotfix/*

  tag:
    patterns:
      - v*
      - release-*

  merge_request:
    branches:
      - main
      - master
    types:
      - merged

environment_mapping:
  develop: dev
  feature/*: dev
  feature/**: dev
  release/*: staging
  hotfix/*: staging
  v*: prod
  release-*: prod
  main: prod
  master: prod

Trigger Types

Trigger	Fields	Description
`push`	`branches`	Fires on push to matching branches
`tag`	`patterns`	Fires when a tag matching the pattern is pushed
`merge_request`	`branches`, `types`	Fires on merge request events to matching branches

Branch Patterns

feature/* — matches one path segment (e.g. feature/login)
feature/** — matches nested segments (e.g. feature/user/auth)
v* — matches tags like v1.0.0, v2.1.3-beta

Environment Mapping

Maps the branch or tag pattern to an environment name. When a webhook fires, the pipeline runner looks up the matching pattern to determine which environment to deploy to.

Workflow Models

Trunk-Based
GitFlow

Development happens on short-lived branches merged to main. Production deploys are triggered by tagging.

feature/* → dev
main      → staging (via push)
v*        → prod (via tag)

Long-lived develop and main branches with release branches for staging.

feature/* → dev
release/* → staging
main      → prod (via merge request)

Parallel Execution (Stage Groups)

Jobs that share the same stage_group and stage_group_order run in parallel:

sast_scan:
  stage: analysis
  stage_group: "Security"
  stage_group_order: 0
  job_name: "SAST Scan"
  parallel_execution: true
  # ...

secret_scan:
  stage: analysis
  stage_group: "Security"
  stage_group_order: 0
  job_name: "Secret Scan"
  parallel_execution: true
  # ...

Both jobs execute simultaneously within the analysis stage.

Helm Chart Integration

The .kodeshift/chart/ directory holds a standard Helm chart used by ArgoCD for deployment.

chart/
├── Chart.yaml
├── values.yaml          # Base values (shared across environments)
├── values-dev.yaml      # Dev-specific overrides
├── values-staging.yaml  # Staging-specific overrides
└── values-prod.yaml     # Production-specific overrides

During deployment, ArgoCD applies values-${ENV}.yaml on top of the base values.yaml, so you only need to specify overrides per environment.

Pipeline Lifecycle

Status	Description
`pending`	Pipeline created, waiting to start
`running`	Currently executing stages
`success`	All stages completed successfully
`success_with_warnings`	Completed, but one or more `allow_fail` stages failed
`failed`	A required stage failed
`cancelled`	Stopped by user
`waiting`	Paused at a `trigger: manual` stage

Built-in Variables

These variables are available in all scripts via ${VARIABLE} syntax.

Variable	Description
`ENV`	Target environment name (e.g. `dev`, `staging`, `prod`)
`IMAGE_TAG`	Docker image tag
`BRANCH_CODE`	Git branch for the application source code
`BRANCH_PIPELINE`	Git branch for pipeline config (usually `kodeshift`)
`APP_NAME`	Application / project name
`NAMESPACE`	Kubernetes namespace for deployment
`CLUSTER_NAME`	Target Kubernetes cluster
`RUN_NAMESPACE`	Namespace where the pipeline job pod runs
`GIT_REPO_URL`	Repository URL (without protocol)
`GIT_TOKEN`	Git access token
`GIT_USERNAME`	Git username
`ARGOCD_SERVER`	ArgoCD server URL
`ARGOCD_TOKEN`	ArgoCD authentication token
`ARGOCD_USERNAME`	ArgoCD username
`ARGOCD_PASSWORD`	ArgoCD password
`ARGOCD_VERSION`	ArgoCD CLI version
`ARGOCD_PROJECT`	ArgoCD project name
`ARGOCD_INSTANCE_ID`	ArgoCD instance identifier
`REGISTRY`	Container registry URL
`REGISTRY_REPO`	Registry repository path
`DOCKERFILE`	Path to Dockerfile (default: `/workspace/Dockerfile`)
`SONAR_HOST_URL`	SonarQube server URL
`SONAR_TOKEN`	SonarQube authentication token
`DOCKER_CONFIG`	Docker config directory path

Sensitive variables like GIT_TOKEN, ARGOCD_PASSWORD, and SONAR_TOKEN are injected from Vault at runtime and are never stored in your YAML files.

Validation Rules

When a pipeline is saved or triggered, the system validates:

Main YAML schema — stages and includes must conform to the expected structure
Included files exist — every path in includes must resolve to a valid file
Stage references — each job’s stage field must match a declared stage name
Environment consistency (legacy dict format only) — environments declared in job files must match those in the stages dict
Common scripts — YAML syntax is validated but references are resolved at runtime

Validation errors include the file path, stage name, and specific mismatch details to help you fix issues quickly.

Complete Example

A minimal but complete pipeline with four stages:

stages:
  - gitleaks
  - analysis
  - build
  - deploy

includes:
  - pipeline/.kodeshift-pipeline.yaml
  - pipeline/.kodeshift-common.yaml
  - pipeline/.kodeshift-trigger.yaml

gitleaks:
  stage: gitleaks
  image:
    name: shiftlabsdev/gitleaks:latest
  script:
    - "@security_scripts"
  init:
    - "@clone_scripts"
  environments:
    - "*"
  allow_fail: true

analysis:
  stage: analysis
  image:
    name: shiftlabsdev/sonar-scanner-cli:latest
  script:
    - "@quality_scripts"
  init:
    - "@clone_scripts"
  environments:
    - "*"
  allow_fail: true

build:
  stage: build
  image:
    name: shiftlabsdev/kaniko-executor:latest
    command:
      - /kaniko/executor
    args:
      - "--dockerfile=${DOCKERFILE}"
      - "--context=dir:///workspace/"
      - "--destination=${REGISTRY}/${REGISTRY_REPO}/${APP_NAME}:${ENV}-${IMAGE_TAG}"
    env:
      - name: DOCKER_CONFIG
        value: /kaniko/.docker
  script: []
  init:
    - "@clone_scripts"
  environments:
    - "*"

deploy:
  stage: deploy
  image:
    name: shiftlabsdev/builder:latest
  script:
    - "@deploy_scripts"
  init:
    - "@clone_scripts"
  environments:
    - "*"

on:
  push:
    branches:
      - develop
      - feature/*
  tag:
    patterns:
      - v*

environment_mapping:
  develop: dev
  feature/*: dev
  v*: prod

Getting Started

Infrastructure

Platform Services

CI/CD & Deployments

Pipeline & Helm

Performance Testing

Security

Mesh Networking

Access Management

Audit & Compliance

Settings

Syntax & Structure

Directory Structure

Main Configuration (`.kodeshift.yaml`)

Fields

Job Definitions (`.kodeshift-pipeline.yaml`)

Field Reference

Image Configuration

Script References

Reference syntax (`@`)

Inline commands

Advanced formats

Common Scripts (`.kodeshift-common.yaml`)

Environment Pattern Matching

Conditional allow_fail

Trigger Configuration (`.kodeshift-trigger.yaml`)

Trigger Types

Branch Patterns

Environment Mapping

Workflow Models

Parallel Execution (Stage Groups)

Helm Chart Integration

Pipeline Lifecycle

Built-in Variables

Validation Rules

Complete Example

​Directory Structure

​Main Configuration (.kodeshift.yaml)

​Fields

​Job Definitions (.kodeshift-pipeline.yaml)

​Field Reference

​Image Configuration

​Script References

​Reference syntax (@)

​Inline commands

​Advanced formats

​Common Scripts (.kodeshift-common.yaml)

​Environment Pattern Matching

​Conditional allow_fail

​Trigger Configuration (.kodeshift-trigger.yaml)

​Trigger Types

​Branch Patterns

​Environment Mapping

​Workflow Models

​Parallel Execution (Stage Groups)

​Helm Chart Integration

​Pipeline Lifecycle

​Built-in Variables

​Validation Rules

​Complete Example

Directory Structure

Main Configuration (`.kodeshift.yaml`)

Fields

Job Definitions (`.kodeshift-pipeline.yaml`)

Field Reference

Image Configuration

Script References

Reference syntax (`@`)

Inline commands

Advanced formats

Common Scripts (`.kodeshift-common.yaml`)

Environment Pattern Matching

Conditional allow_fail

Trigger Configuration (`.kodeshift-trigger.yaml`)

Trigger Types

Branch Patterns

Environment Mapping

Workflow Models

Parallel Execution (Stage Groups)

Helm Chart Integration

Pipeline Lifecycle

Built-in Variables

Validation Rules

Complete Example