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.

Configuration

atmos.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"
    container:
      image: "image.md"

ci.templates.base_path

Directory containing custom template files. A relative path resolves against the Atmos base_path, not against the repository root or the working directory. An absolute path is used as written. The .atmos/ci/templates value in the examples on this page is a suggested location, not a default.

Default: None. Without it, only files named by absolute path and the built-in templates are used.

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.

ci.templates.container.image

Filename of the custom container image summary template within the base path. A configured file that does not exist is an error, so a typo cannot silently revert to the built-in template. Without the key, Atmos uses <base_path>/container/image.md when that file exists, and the built-in template otherwise. The same Markdown is used for the job summary and for the per-image comment, keyed container:image:<registry/repository>. The comment targets the pull request when one is known, or the commit otherwise. GitHub commit comments require contents: write permission.

The template receives these fields, all already escaped Markdown: .Image, .Badges, .Description, .Tag, .Digest, .ID, .Revision, .Source, .Entrypoint, .Command, .StopSignal, .StorageDriver, .ExposedPorts, .Env (rows with .Name and .Value), .Labels (rows with .Name and .Value), .Layers (rows with .Index and .Digest), and .RawJSON.

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 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 to load a different template name from <base_path>/kubernetes/<name>.md.

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

.atmos/ci/templates/plan.md

## {{ .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 }}

Script report templates

Scripts that call ci.summary or ci.comment can render their text from a template file instead of building the Markdown in code. The call names the template, and the configuration only says where template files live. Scripts have no configured default template.

atmos.yaml

ci:
  templates:
    base_path: ".atmos/ci/templates"

ci.summary(template = "deploy.md", data = {"stack": "prod", "count": 2, "services": ["api", "web"]})
ci.comment(template = "release.md", data = {"version": "1.4.0"}, key = "release")

A call that passes data must also pass template. A call with data and no template fails with an argument error that asks for template=.

A template name resolves against ci.templates.base_path, so deploy.md above is read from .atmos/ci/templates/deploy.md. An absolute path is used as written. When no file has exactly that name, the name with a .md suffix is tried, so deploy finds deploy.md. The data dict that the script passes is the template context, and keys are read as .key. A key that the template reads but data does not contain fails the render and names the key, so a typo never renders <no value>. A template that cannot be found fails the script with the resolved path and the value of ci.templates.base_path.

.atmos/ci/templates/deploy.md

## Deploy to {{ .stack }}

{{ .count }} services deployed.
{{ range .services }}
- {{ . }}
{{ end }}

The ci.summary.template key belongs to the native commands. They read it as the name of a summary template for the component type (for example <base_path>/kubernetes/summary.md), and scripts never read it, so setting it cannot change what a script renders. There is no comment counterpart: native plan comments reuse the rendered plan summary, and scripts name their comment template in the call.

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 - Full configuration reference
• Summary - Job summary configuration
• Comments - PR comment configuration
• ci.summary and ci.comment - Script functions that render these templates
• Job Summaries - Summary format and template customization