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
ci.templates.base_pathDirectory 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/templatesvalue 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.planFilename of the custom plan summary template within the base path.
Default: Built-in template
ci.templates.terraform.applyFilename of the custom apply summary template within the base path.
Default: Built-in template
ci.templates.terraform.destroyFilename of the custom Terraform destroy summary template within the base path.
Default:
destroy.md(built-in)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.imageFilename 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.mdwhen that file exists, and the built-in template otherwise. The same Markdown is used for the job summary and for the per-image comment, keyedcontainer:image:<registry/repository>. The comment targets the pull request when one is known, or the commit otherwise. GitHub commit comments requirecontents: writepermission.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.Nameand.Value),.Labels(rows with.Nameand.Value),.Layers(rows with.Indexand.Digest), and.RawJSON.ci.templates.artifacts.summaryFilename of the custom template for the whole artifact report (the heading, the overview table, and the per-operation sections) within the base path. See Artifacts.
ci.templates.artifacts.<action>Filename of the custom template for the section of one artifact operation, where
<action>ispublish,pull,copy,inspect,list,search,delete,show,sign,verify, orpin. The other operations keep the built-in section. A configured file that does not exist is an error.
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 |
Artifacts
Artifact operations write one report per command,
workflow, custom command, or hook. The report is two layers of templates, each resolved in the usual order: the
file named under ci.templates.artifacts, then <base_path>/artifacts/<name>.md, then the built-in template.
summaryis the frame: the heading, the overview table, and where the operation sections go.<action>(publish,pull,copy, and so on) is the section of one operation. Every action has the same built-in section, so you can override one action without touching the others.
A file named under ci.templates.artifacts that does not exist fails the report with an error that names the
resolved path, so a typo never silently reverts to the built-in template. The failure is logged as a warning and
never changes the exit status of the artifact operation. Output variables do not depend on the template and are
still written.
Every string the templates receive is already escaped Markdown, with secrets masked and URL credentials and query strings removed. Print the fields as they are. Strings shown here as code spans arrive wrapped in backticks.
The summary template receives:
| Variable | Type | Description |
|---|---|---|
.Heading | string | The report heading text |
.Overview | string | One-line count of operations and outcomes |
.Total, .Succeeded, .Unchanged, .Failed, .Canceled | int | Operation counts. An unchanged operation counts once, as unchanged |
.Rows | []object | Overview rows: .Number, .Operation, .Icon, .Status, .Artifact, .Repository, .Destination, .Digest, .Size, .Duration |
.Sections | []string | The rendered per-operation sections, in report order |
.Omitted | int | Sections left out to fit the size limit |
.Notice | string | Visible note about a size-reduced report, empty for a complete one |
An <action> template receives one operation:
| Variable | Type | Description |
|---|---|---|
.Number, .Title, .Summary | Position in the report, the heading text, and a one-sentence statement | |
.Action, .ActionLabel, .Step | string | The action, its title-cased form, and the step name (empty outside a step) |
.Icon, .Status, .Kind | string | Status symbol, wording such as Published, and the kind: success, unchanged, dry-run, unchecked, incomplete, failed, or canceled |
.Repository, .Requested, .Ref, .Destination | string | Code spans. .Requested is empty when it equals .Ref |
.Aliases | []string | Other locations or tags that resolve to the same content |
.Size, .ExactSize, .Duration | string | Human-readable values, empty when the operation has none |
.Attempts | int | Attempts taken; the report shows the final one |
.Lock | object | .Scope (host, repository, or none) and .Guarantee; empty for reads |
.Digests | []object | .Label (Resolved, Record, Content, Representation), .Meaning, .Value, .Short |
.Integrity | string | What the digests prove and what they do not |
.Signature | object | .Status (signed, verified, unchecked, failed), .Statement, .SubjectKind, .SubjectDigest, .Policy, .Claims (.Identity, .Issuer, .KeyID), .Evidence (.Format, .Digest); empty unless the operation signed or verified |
.Error | string | A fenced code block with the error of a failed operation |
.Diagnostics, .DiagnosticsMore | []object, int | Non-fatal messages (.Severity, .Code, .Message) and how many more were not shown |
.Description, .Labels, .Inventory | Record metadata and the payload listing (.Count, .Bytes, .Files, .More) | |
.Collection | object | For list and search: .Count, .Incomplete, .Repositories, .Artifacts, .More |
Summaries stay within 1 MiB, the GitHub step summary limit, with room for content that earlier steps wrote. A larger report first drops the inventory and metadata details, then trailing operation sections, and only then cuts the text. Each step is announced in a visible notice, and the overview table always lists every operation.
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.
Example Custom Template
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.
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.
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/ - Artifacts:
pkg/artifact/report/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.summaryandci.comment- Script functions that render these templates- Job Summaries - Summary format and template customization