# CI PR Comments

The `ci.comments` section configures automatic comments on pull requests (GitHub) or merge requests
(GitLab) with plan summaries, similar to tools like tfcmt and atlantis.

> ⚠️ Experimental

## Configuration

**File:** `atmos.yaml`

```yaml
ci:
  comments:
    enabled: true
    behavior: upsert
```

- **`ci.comments.enabled`**

  Post or update comments on PRs (GitHub) or MRs (GitLab) with plan summaries.

  **Requires:** `pull-requests: write` permission (GitHub) or API token with MR notes scope (GitLab)

  **Default:** `true`

  **Environment variable:** `ATMOS_CI_COMMENTS_ENABLED` — overrides this setting when set.
- **`ci.comments.behavior`**

  How to handle comments:
  - `create` — Always create a new comment
  - `update` — Update existing comment or fail if none exists
  - `upsert` — Update existing comment or create new one (recommended)
  Comments are identified by an HTML marker for the component/stack combination, so each
  component gets its own comment that is updated on subsequent runs.

  **Default:** `upsert`

## Environment Variables

| Variable | Description |
|----------|-------------|
| `ATMOS_CI_COMMENTS_ENABLED` | Override `ci.comments.enabled` (`true`/`false`). Takes precedence over the YAML configuration when set. |

## GitHub Actions Permissions

PR comments require the `pull-requests: write` permission:

```yaml
permissions:
  pull-requests: write
```

## Custom Templates

Override the default comment templates with your own Markdown. See [Templates](/cli/configuration/ci/templates)
for configuration and template variables.

## Related

- [CI Configuration](/cli/configuration/ci) - Full configuration reference
- [Templates](/cli/configuration/ci/templates) - Custom template configuration
- [Native CI Overview](/ci) - Feature overview