notifications

The notifications configuration controls what Terrateam posts back to a pull request: the comment update strategy for different directories and workspaces, the summary of a run, whether the normal plan and apply comments are posted at all, and whether the per-dirspace status checks are created.

Default Configuration

notifications:
  policies:
    - tag_query: ''
      comment_strategy: 'minimize'
  summary:
    # enabled has no default of its own.  An unset enabled means on in the
    # Enterprise Edition and off in the Open Source Edition.
    mode: pull_request
    output_details:
      enabled: false
  plan:
    visible_on: always
    status_checks:
      enabled: true
  apply:
    visible_on: always
    status_checks:
      enabled: true

Keys

Key	Type	Description
policies	array	A list of notification policy objects that specifies which comment update strategies apply for particular tags .
summary	object	Controls the summary of a run: the header at the top of plan and apply comments, or one comment per pull request.
plan	object	Controls the normal per-run plan comment and the per-dirspace plan status check.
apply	object	Controls the normal per-run apply comment and the per-dirspace apply status check.

Policies

Key	Type	Description
comment_strategy	string	Specifies the strategy Terrateam will use when creating new comments. Values are append (don’t modify old comments, just keep appending), minimize (old comments get minimized) or delete (old comments get removed). Default is minimize.
tag_query	string	See tag queries. Required.

Summary

Note

The summary header is an Enterprise feature. Enabling it on the Open Source Edition is not supported: Terrateam will post a message that this is a commercial feature instead of running the operation.

Key	Type	Description
enabled	boolean	When true, each plan and apply comment starts with a summary header: a one-line rollup and a table of the dirspaces (directory and workspace combinations) executed in that comment, with their result and, for plans, the created, updated, replaced, and deleted resource counts reported by the runner. A runner or engine that does not report counts renders -. This lets reviewers see what a comment covers without expanding the full output. The key has no default of its own: leaving it out means enabled on the Enterprise Edition and disabled on the Open Source Edition, where the summary is not available.
mode	string	How the summary is presented. Values are header (the per-comment summary header described above) or pull_request (a single unified summary comment maintained for the whole pull request). Default is pull_request.
output_details.enabled	boolean	When true, the summary comment includes an inline output details section with the plan output. Default is false; the plan output is available in the Terrateam console via the links in the table.

The summary header is rendered above the collapsed plan/apply output. On the Enterprise Edition it is on unless you turn it off:

notifications:
  summary:
    enabled: false

Plan and Apply

plan and apply decide what a run of that kind posts back: its comment, and its per-dirspace status check. They are configured on their own, beside summary and not inside it, so they take effect whether or not the summary is enabled and in either mode. They are not an Enterprise feature.

Key	Type	Description
plan.visible_on	string	When the normal per-run plan comment is posted. Values are always, failure, success, or never. Default is always.
plan.status_checks.enabled	boolean	When true, each dirspace of a plan gets its own status check, terrateam plan: <directory> <workspace>. Default is true.
apply.visible_on	string	When the normal per-run apply comment is posted. Values are always, failure, success, or never. Default is always.
apply.status_checks.enabled	boolean	When true, each dirspace of an apply gets its own status check, terrateam apply: <directory> <workspace>. Default is true.

Results carrying gate approvals or access control denials always post their comment, whatever visible_on is set to, because nothing else carries them.

In header mode the summary header lives inside the plan or apply comment, so a comment that visible_on hides takes its header with it.

status_checks covers only the per-dirspace checks. The other checks Terrateam creates are not affected:

• terrateam apply, the check that stays pending until every changed dirspace is applied. This is the check to require in branch protection, and it is always created.
• terrateam index, terrateam build-config and terrateam build-tree, which belong to other operations.

A run used to post two checks of its own as well, terrateam plan pre-hooks and terrateam plan post-hooks, and the same pair for an apply. They are no longer created: they reported what the run’s comment already reports. A pull request opened before this change can still carry one; Terrateam completes it once every changed dirspace of that pull request is applied.

A repository with many dirspaces gets one check per dirspace per run, which is what turning these off is for. The setting applies to every run of that kind, including drift.

notifications:
  plan:
    visible_on: never
    status_checks:
      enabled: false
  apply:
    visible_on: failure
    status_checks:
      enabled: false

Pull Request Mode

With mode: pull_request, Terrateam maintains one summary comment per pull request instead of a header on every plan and apply comment. The comment is posted as soon as a run starts, before the run can post any result comment, so it is always Terrateam’s first comment on the pull request; while a run is in flight its dirspaces show as Plan Running or Apply Running. As each run finishes, the comment is updated in place, so reviewers always have a single up-to-date view of the pull request.

The unified comment contains a table with one row per dirspace (directory and workspace combination):

• Status: one of
  • Pending: the dirspace is in the pull request and nothing has run for it yet.
  • Plan Running: a plan is in flight and has produced nothing for the dirspace yet.
  • Apply Running: the apply of a plan that is already in the table is in flight.
  • Planned: a plan succeeded and is waiting for an apply.
  • Applied: the apply succeeded.
  • Failed: the plan or the apply failed, or the run was aborted before it produced a result.
• Change counts: Created, Updated, Replaced, and Deleted, reported by the runner in the plan step’s resource summary. A runner or engine that does not report them renders -.
• Link: a per-dirspace link to the Terrateam console.

A totals row sums the change counts across all dirspaces. Rows are sorted with failures first, then dirspaces with changes.

In this mode the regular per-run plan and apply output comments post as usual alongside the summary comment, with their per-dirspace changes table collapsed into a details block whose summary line shows the totals of the table, since the summary comment carries the full rollup. In header mode the plan and apply tables are never collapsed. Use plan.visible_on and apply.visible_on above to post fewer of these comments; with never the summary comment is the only one, and the full output is available in the Terrateam console via the links in the table.

If the table is too large to fit in a single comment, it is truncated to the top rows with a link to the console for the full list.

Enable it (Enterprise only):

notifications:
  summary:
    enabled: true
    mode: pull_request

Both mode values require enabled: true, which is an Enterprise feature.

Examples

Multiple Comment Strategies for Different Dirspaces

notifications:
  policies:
    - tag_query: 'dir:tf1'
      comment_strategy: 'minimize'

    - tag_query: 'dir:tf2'
      comment_strategy: 'delete'

This configuration will apply different rules for two different dirspaces (dir:tf1 and dir:tf2).