customization

Customize Lunar's presentation and behavior.

• lunar-config.yml -> customization
• Type: object
• Optional

The customization object controls optional changes to Lunar's presentation and behavior.

bypass_template

• lunar-config.yml -> customization.bypass_template
• Type: string
• Optional

The path to a Go text/template used for the reply after a comment-driven pull-request or merge-request bypass succeeds:

customization:
  bypass_template: templates/bypass-acknowledgement.tmpl.md

The path is relative to the configuration repository root, even when the customization: block is in lunar-config.d/.

Lunar reads and validates the file when it pulls the configuration, then stores the template with the manifest. Hub replicas render the stored content and do not need access to the repository checkout. A missing file, invalid template, or unsupported parameter fails the pull before a new manifest is created or published.

templates/bypass-acknowledgement.tmpl.md

**Earthly Lunar merge gate bypassed** by @{{ .Actor }} for commit `{{ .SHA }}`.

Reason: {{ .Reason }}

This override covers only the commit above — pushing a new commit re-arms the gate. Inspect it with `lunar policy bypass-ls`, or revoke it early with `lunar policy bypass-rm`.

Templates receive this typed data:

• .Actor (string): Git platform username or login, without @
• .SHA (string): full pull-request or merge-request head commit SHA
• .Reason (string): supplied reason, collapsed to one line before rendering
• .PullRequestNumber (int64): repository-local pull-request or merge-request number
• .GitPlatform (string): canonical Git platform name, such as github or gitlab
• .Host (string): Git platform host
• .Repository (string): owner/repository path
• .SourceBranch and .TargetBranch (string): pull-request or merge-request branches
• .Components ([]string): all matched Lunar component names
• .SelfBypass (bool): whether the commenter authored the pull request or merge request
• .VerifiedRole (string): provider-qualified role recorded in the bypass ledger, such as gitlab:maintainer

Standard text/template syntax and its non-allocating built-in functions are available. Lunar does not add template helper functions, and missing or unsupported parameters are errors. To keep rendering work bounded, call, html, js, print, printf, println, urlquery, and with are not available; recursive or overly complex template-call graphs are rejected; and a template may contain one range, directly over .Components.

If this field is omitted, Lunar uses its built-in acknowledgement.

For safety, the template file and rendered output must each be no larger than 64 KiB, and output must be non-empty. Output must not contain the reserved [Earthly Lunar] results-comment marker or any line whose first non-whitespace character is /, since Git platforms may interpret such lines as commands. Lunar checks custom templates during configuration pull and checks the actual output again before posting. If a stored custom template unexpectedly fails at runtime, Lunar logs the error and posts the built-in acknowledgement.

pr_comments

• lunar-config.yml -> customization.pr_comments
• Type: object
• Optional

The pr_comments object controls when Earthly posts its results comment on a pull or merge request. It affects only the comment; commit statuses and the merge gate keep posting on every run.

customization:
  pr_comments:
    mode: only-failures

mode

• lunar-config.yml -> customization.pr_comments.mode
• Type: string
• Optional
• Default: always

When the results comment is posted. One of:

• always — post the comment and keep it updated on every run, including the live "pending" view while collectors are still reporting. This is the default and the historical behavior.
• only-failures — stay quiet until the first failure. While every displayed check passes and Earthly has not yet commented on the request, no comment is posted. The first failing, erroring, or still-pending result posts the comment, and from then on it keeps updating as usual, back to all-green once the failure is fixed.

The trade-off of only-failures is that an all-green request has no comment, so there is no live view of collectors that have not finished yet. The first failure still surfaces as soon as it happens.

checks_template

• lunar-config.yml -> customization.checks_template
• Type: string
• Optional

Use a repository-relative Go text/template to control the full Markdown checks report:

customization:
  checks_template: templates/checks-report.tmpl.md

Lunar resolves the path from the configuration repository root, including when the customization: block is in lunar-config.d/. It rejects absolute paths, paths outside the repository, and symlinks that resolve outside it.

Without checks_template, Lunar uses the standard built-in Earthly Lunar report.

One template controls these report bodies:

• GitHub Check Run text (github-check)
• GitHub pull request comments (github-pr-comment)
• GitLab merge request notes (gitlab-mr-note)

The template cannot change check names, GitHub conclusions, GitLab states, required-check calculation, bypass decisions, or heartbeat behavior.

Template data

The template receives these fields:

• .GitPlatform: github or gitlab
• .Surface: github-check, github-pr-comment, or gitlab-mr-note
• .Host: Git platform host
• .Repository: owner and repository path
• .Component: full Lunar component name
• .SHA: commit being reported
• .PullRequestNumber: pull request or merge request number, or 0 for a default-branch check
• .DetailsURL: Lunar dashboard URL
• .Bypassed: bypassed checks
• .Sections: checks grouped by status

The built-in template is:

### 🌙 [Earthly Lunar](https://docs-lunar.earthly.dev/)

{{if .Bypassed}}<details open>
<summary><strong>🔓 {{len .Bypassed}} Bypassed</strong></summary>
{{if eq .GitPlatform "github"}}<br>
{{end}}
*These required checks were failing, but an active bypass lets them through. The merge gate treats them as passing until the bypass expires or is revoked.*

{{range .Bypassed}}* 🔓 `{{.Name}}` — bypassed by {{.Actor}} {{if .CommitBound}}while its commit stands{{else}}until {{.ExpiresAt}}{{end}}: {{.Reason}}
{{range .FailureMessages}}  * {{.}}
{{end}}{{if gt .MoreAssertions 0}}  * {{.MoreAssertions}} more assertions weren't shown
{{end}}{{end}}
</details>

{{end}}{{range .Sections}}<details{{if .Open}} open{{end}}>
<summary><strong>{{template "section-icon" .}} {{.Count}} {{.Title}}</strong></summary>
{{if eq $.GitPlatform "github"}}<br>
{{end}}
{{if .Summary}}{{if eq .Status "error"}}*{{.Summary}}*{{else}}{{.Summary}}{{end}}

{{end}}{{if and (eq .Status "fail") .HasRequired}}*To bypass the required checks, comment with `/lunar bypass: <reason>`*

{{end}}{{range .Checks}}* {{template "check-icon" .}} `{{.Name}}`{{if .Description}} - {{.Description}}{{end}}
{{range .FailureMessages}}  * {{.}}
{{end}}{{if gt .MoreAssertions 0}}  * {{.MoreAssertions}} more assertions weren't shown
{{end}}{{if .Error}}  * `{{.Error}}`
{{end}}{{end}}{{if .AdditionalChecks}}
<details>
<summary>{{len .AdditionalChecks}} more...</summary>

{{range .AdditionalChecks}}* {{template "check-icon" .}} `{{.Name}}`{{if .Description}} - {{.Description}}{{end}}
{{range .FailureMessages}}  * {{.}}
{{end}}{{if gt .MoreAssertions 0}}  * {{.MoreAssertions}} more assertions weren't shown
{{end}}{{if .Error}}  * `{{.Error}}`
{{end}}{{end}}</details>
{{end}}
</details>

{{end}}{{if and .DetailsURL (or .Sections .Bypassed)}}[More Details]({{.DetailsURL}})

{{end -}}
{{define "section-icon"}}{{if eq .Status "fail"}}{{if .HasRequired}}❌{{else}}⚠️{{end}}{{else if eq .Status "no-data"}}⏱️{{else if eq .Status "pass"}}✅{{else if eq .Status "error"}}❗{{else}}⁉️{{end}}{{end -}}
{{define "check-icon"}}{{if eq .Status "fail"}}{{if .Required}}❌{{else}}⚠️{{end}}{{else if eq .Status "no-data"}}⏱️{{else if eq .Status "pass"}}✅{{else if eq .Status "error"}}❗{{else}}⁉️{{end}}{{end -}}

Templates can use standard text/template actions and built-in functions. Lunar sets missingkey=error and does not expose Git platform API objects or custom helper functions.

Lunar reads and validates the file during configuration pull. It rejects the pull if the file is missing or the template has an error, refers to an unknown field, renders an empty or oversized report, or produces a line beginning with /. The last published manifest remains active.

Before rendering, Lunar collapses every data value to one line, except failure messages: their lines survive, and each line after the first is re-emitted as an indented list item, so multi-line findings render as a nested list. Either way a value never opens a line of the report, which prevents a check name, assertion, or bypass reason from injecting a GitLab quick action.

If a validated custom template still fails at runtime, Lunar logs the error and uses the built-in report for that update.