# CI Templates

The `ci.templates` section configures custom Markdown templates for job summaries and PR comments.
Templates use Go template syntax with access to plan/apply context data.

> ⚠️ Experimental

## Configuration

**File:** `atmos.yaml`

```yaml
ci:
  templates:
    base_path: ".atmos/ci/templates"
    terraform:
      plan: "plan.md"
      apply: "apply.md"
    helm:
      template: "helm-template.md"
      diff: "helm-diff.md"
      apply: "helm-apply.md"
      delete: "helm-delete.md"
    helmfile:
      template: "helmfile-template.md"
      diff: "helmfile-diff.md"
      apply: "helmfile-apply.md"
      destroy: "helmfile-destroy.md"
```

- **`ci.templates.base_path`**

  Directory containing custom template files, relative to the repository root.

  **Default:** `.atmos/ci/templates`
- **`ci.templates.terraform.plan`**

  Filename of the custom plan summary template within the base path.

  **Default:** Built-in template
- **`ci.templates.terraform.apply`**

  Filename of the custom apply summary template within the base path.

  **Default:** Built-in template
- **`ci.templates.helm.template`**
  Filename of the custom native Helm template/render summary template within the base path.
- **`ci.templates.helm.diff`**
  Filename of the custom native Helm diff/plan summary template within the base path.
- **`ci.templates.helm.apply`**
  Filename of the custom native Helm apply/deploy summary template within the base path.
- **`ci.templates.helm.delete`**
  Filename of the custom native Helm delete/destroy summary template within the base path.
- **`ci.templates.helmfile.template`**
  Filename of the custom Helmfile template summary template within the base path.
- **`ci.templates.helmfile.diff`**
  Filename of the custom Helmfile diff summary template within the base path.
- **`ci.templates.helmfile.apply`**
  Filename of the custom Helmfile apply/sync/deploy summary template within the base path.
- **`ci.templates.helmfile.destroy`**
  Filename of the custom Helmfile destroy summary template within the base path.

## Template Context

Templates receive a context object for the operation being summarized.

All native CI summary templates receive these common fields when available:

| Variable | Type | Description |
|----------|------|-------------|
| `.Component` | string | Component name |
| `.Stack` | string | Stack name |
| `.Command` | string | Normalized command name used for template selection |
| `.Success` | bool | Whether the operation succeeded |
| `.ExitCode` | int | Command exit code |
| `.Error` | string | Error message when the command failed |
| `.ReproductionCommand` | string | Local command to reproduce the operation |

### Terraform Plan Template Variables

| Variable | Type | Description |
|----------|------|-------------|
| `.Component` | string | Component name |
| `.Stack` | string | Stack name |
| `.Command` | string | Terraform command (`plan`) |
| `.HasChanges` | bool | Whether the plan has changes |
| `.Additions` | int | Number of resources to create |
| `.Changes` | int | Number of resources to change |
| `.Destructions` | int | Number of resources to destroy |
| `.Imports` | int | Number of resources to import |
| `.Summary` | string | One-line plan summary |
| `.Resources` | object | Resource lists by action type |
| `.Warnings` | \[]string | Terraform warning messages |

### Terraform Apply Template Variables

| Variable | Type | Description |
|----------|------|-------------|
| `.Component` | string | Component name |
| `.Stack` | string | Stack name |
| `.Command` | string | Terraform command (`apply`) |
| `.Success` | bool | Whether apply succeeded |
| `.Summary` | string | One-line apply summary |
| `.Resources` | object | Resource lists by action type |
| `.Outputs` | map | Terraform outputs |
| `.Warnings` | \[]string | Terraform warning messages |

### Helm Template Variables

Native Helm summary templates also receive Helm metadata when available:

| Variable | Type | Description |
|----------|------|-------------|
| `.ReleaseName` | string | Helm release name |
| `.Namespace` | string | Kubernetes namespace |
| `.Chart` | string | Chart reference |
| `.Target` | string | Provision target, when one was selected |
| `.ObjectCount` | int | Number of rendered or applied Kubernetes objects |
| `.Kinds` | map | Rendered or applied Kubernetes object counts by kind |
| `.ManifestBytes` | int | Rendered manifest size in bytes |
| `.Diff` | string | Unified diff produced by `diff`/`plan` (rendered as a collapsible diff block; Secret values redacted) |

`render` uses the `template` template, `plan` uses `diff`, `deploy` uses `apply`, and `destroy` uses `delete`.

### Helmfile Template Variables

Helmfile summary templates also receive captured command output:

| Variable | Type | Description |
|----------|------|-------------|
| `.Output` | string | Combined masked stdout/stderr captured from the Helmfile command |

`sync` and `deploy` use the `apply` template.

### Kubernetes Summary Template Variables

Native [Kubernetes components](/cli/commands/kubernetes/usage) render a single summary
template (default name `summary`) for every command (`render`, `plan`, `diff`, `apply`,
`deploy`, `delete`, `validate`). For `plan`/`diff`, the `.Diff` variable holds the aggregated
unified diff of all changed objects (rendered as a collapsible diff block using GitHub's `diff`
fenced code syntax). `Secret` objects are deliberately omitted from `.Diff` so their data never
reaches the job summary.

| Variable | Type | Description |
|----------|------|-------------|
| `.Component` | string | Component name |
| `.Stack` | string | Stack name |
| `.Command` | string | Kubernetes command (`plan`, `diff`, `apply`, …) |
| `.Status` | string | `failed`, `changed`, `no changes`, or `succeeded` |
| `.ObjectsTotal` | int | Number of objects processed |
| `.Counts` | \[]object | Action counts, each with `.Action` and `.Count` |
| `.Actions` | \[]object | Per-object rows: `.Action`, `.Resource`, `.Namespace`, `.Name`, `.Diff` |
| `.Diff` | string | Aggregated unified diff across changed objects (Secrets omitted, truncated) |
| `.Error` | string | Command error message, if any |

## Customizing the Kubernetes Summary

Kubernetes summaries resolve by the base-path convention rather than the `terraform`/`helmfile`
override maps. Place a file at `<base_path>/kubernetes/summary.md` to override the embedded
default, or set [`ci.summary.template`](/cli/configuration/ci/summary) to load a different
template name from `<base_path>/kubernetes/<name>.md`.

**File:** `atmos.yaml`

```yaml
ci:
  templates:
    base_path: ".atmos/ci/templates"   # kubernetes summary read from kubernetes/summary.md
  summary:
    template: "summary"                 # optional: load kubernetes/<template>.md instead
```

## Example Custom Template

**File:** `.atmos/ci/templates/plan.md`

```markdown
## {{ .Component }} / {{ .Stack }}

{{ if .HasChanges }}
**Changes detected:** {{ .Additions }} to add, {{ .Changes }} to change, {{ .Destructions }} to destroy

{{ if gt .Destructions 0 }}
> **Warning:** This plan destroys resources!
{{ end }}
{{ else }}
No changes. Infrastructure is up-to-date.
{{ end }}
```

## Built-in Templates

The default templates are embedded in the Atmos binary:

- Terraform: `pkg/ci/plugins/terraform/templates/`
- Helm: `pkg/ci/plugins/helm/templates/`
- Helmfile: `pkg/ci/plugins/helmfile/templates/`
- Kubernetes: `pkg/ci/plugins/kubernetes/templates/`

You can use these as a starting point for customization.

## Related

- [CI Configuration](/cli/configuration/ci) - Full configuration reference
- [Summary](/cli/configuration/ci/summary) - Job summary configuration
- [Comments](/cli/configuration/ci/comments) - PR comment configuration
- [Job Summaries](/ci/job-summaries) - Summary format and template customization