> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Syntax & Structure

> YAML reference for KodeShift CI/CD pipelines

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
```

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

## Main Configuration (`.kodeshift.yaml`)

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

```yaml theme={null}
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                                                         |

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

## 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`.

```yaml theme={null}
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                            |

<Note>Both `snake_case` and `camelCase` field names are accepted (e.g. `stage_group` or `stageGroup`).</Note>

### 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`:

```yaml theme={null}
init:
  - "@clone_scripts"
script:
  - "@security_scripts"
```

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

### Inline commands

```yaml theme={null}
script:
  - "echo 'Hello'"
  - |
    echo "Multiline"
    echo "Commands"
```

### Advanced formats

Scripts can also be objects:

```yaml theme={null}
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 `@`:

```yaml theme={null}
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:

```yaml theme={null}
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.

```yaml theme={null}
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

<Tabs>
  <Tab title="Trunk-Based">
    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)
    ```
  </Tab>

  <Tab title="GitFlow">
    Long-lived `develop` and `main` branches with release branches for staging.

    ```
    feature/* → dev
    release/* → staging
    main      → prod (via merge request)
    ```
  </Tab>
</Tabs>

## Parallel Execution (Stage Groups)

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

```yaml theme={null}
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

```mermaid theme={null}
stateDiagram-v2
    [*] --> pending
    pending --> running : Job starts
    pending --> cancelled : User cancels
    running --> success : All stages pass
    running --> success_with_warnings : allow_fail stages failed
    running --> failed : Non-allow_fail stage failed
    running --> cancelled : User cancels
    running --> waiting : Manual trigger stage reached
    waiting --> running : User approves
    waiting --> cancelled : User cancels
```

| 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                            |

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

## Validation Rules

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

1. **Main YAML schema** — `stages` and `includes` must conform to the expected structure
2. **Included files exist** — every path in `includes` must resolve to a valid file
3. **Stage references** — each job's `stage` field must match a declared stage name
4. **Environment consistency** (legacy dict format only) — environments declared in job files must match those in the `stages` dict
5. **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:

<CodeGroup>
  ```yaml .kodeshift.yaml theme={null}
  stages:
    - gitleaks
    - analysis
    - build
    - deploy

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

  ```yaml .kodeshift-pipeline.yaml theme={null}
  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:
      - "*"
  ```

  ```yaml .kodeshift-trigger.yaml theme={null}
  on:
    push:
      branches:
        - develop
        - feature/*
    tag:
      patterns:
        - v*

  environment_mapping:
    develop: dev
    feature/*: dev
    v*: prod
  ```
</CodeGroup>