Skip to content

docs: add PRD for pro summary upload#2259

Open
goruha wants to merge 1 commit intomainfrom
prd/pro-summary-upload
Open

docs: add PRD for pro summary upload#2259
goruha wants to merge 1 commit intomainfrom
prd/pro-summary-upload

Conversation

@goruha
Copy link
Member

@goruha goruha commented Mar 26, 2026

Summary

  • Adds PRD for uploading structured CI summary data to Atmos Pro via the existing instance status PATCH endpoint
  • Extends InstanceStatusUploadRequest DTO with a nested CI block containing resource counts, terraform outputs, warnings, errors, and base64-encoded output log
  • Gated on --upload-status flag + ci.enabled — backward compatible via omitempty pointer

Test plan

  • Review PRD content for completeness and accuracy
  • Validate API contract with Atmos Pro backend team

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Added documentation describing how the CLI uploads terraform execution signals and diagnostics alongside instance status when configured.

Add product requirements document for uploading structured CI summary
data (resource counts, terraform outputs, warnings, errors, output log)
to Atmos Pro via the existing instance status PATCH endpoint.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@goruha goruha requested a review from a team as a code owner March 26, 2026 22:11
@goruha goruha added the no-release Do not create a new release (wait for additional code changes) label Mar 26, 2026
@github-actions github-actions bot added the size/m Medium size PR label Mar 26, 2026
@github-actions
Copy link

Dependency Review

✅ No vulnerabilities or license issues found.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA ecbc4cc.
Ensure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice.

Scanned Files

None

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Mar 26, 2026

📝 Walkthrough

Walkthrough

A new product requirements document is added describing how the CLI extends instance status upload requests to Atmos Pro. The doc specifies a DTO extension including optional terraform plan/apply metrics (change/error flags, resource counts, outputs, warnings, errors, and base64 stdout log) with conditional gating via --upload-status flag and ci.enabled config.

Changes

Cohort / File(s) Summary
Documentation
docs/prd/pro-summary-upload.md
New PRD documenting CI data extension for instance status uploads. Covers DTO structure for InstanceStatusCI block, API payload shape, gating conditions, and warn-only error handling for terraform parsing failures.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Suggested reviewers

  • aknysh
  • osterman
🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'docs: add PRD for pro summary upload' directly and clearly describes the main change—adding a new product requirements document for pro summary upload functionality.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch prd/pro-summary-upload

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/prd/pro-summary-upload.md`:
- Around line 59-63: Update the PRD to require explicit secret-redaction and
payload-size limits for the CI output fields: enforce that ci.outputs and the
OutputLog (json:"output_log", referenced as OutputLog) must have sensitive
values masked or dropped (e.g., remove tokens, credentials, secrets), include a
description of the redaction strategy (masking pattern or drop-on-detect) and
add a max payload size limit with behavior on overflow (truncate output, include
truncation metadata and byte counts). Also apply the same requirements to the
other CI output sections noted (the other ci.outputs/ci.output_log occurrences)
so all mentions include the redaction rule, truncation policy, and metadata
requirements.
- Around line 133-140: The PRD shows an unsafe direct type assertion on
result.Data (e.g., result.Data.(*TerraformOutputData).Outputs) which can panic;
update the steps that map ParseOutput()'s OutputResult into InstanceStatusCI to
use a safe assertion pattern: call terraform.ParseOutput(), then check the
assertion like data, ok := result.Data.(*TerraformOutputData) and only read
data.ResourceCounts, data.Outputs (converting TerraformOutput.Value to raw
values), and data.Warnings when ok is true, otherwise set Defaults/empty values
and propagate result.Errors into InstanceStatusCI.Errors; mention the use of the
ok boolean and fallback behavior when mapping HasChanges, HasErrors,
ResourceCounts, Outputs, Warnings, and Errors.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ec11f5ac-c3ff-484f-a00c-90d9c759185f

📥 Commits

Reviewing files that changed from the base of the PR and between 2be2909 and ecbc4cc.

📒 Files selected for processing (1)
  • docs/prd/pro-summary-upload.md

Comment on lines +59 to +63
// OutputLog contains the raw terraform stdout captured during command execution,
// base64-encoded. This preserves the full output including ANSI formatting
// for server-side rendering and debugging.
OutputLog string `json:"output_log,omitempty"`
}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Add explicit secret-redaction and payload-size limits for ci.outputs and ci.output_log.

Right now the PRD requires shipping raw outputs and full stdout, which can leak secrets and can blow request size on large plans/applies. Add requirements for masking sensitive values (or dropping them), stripping tokens/credentials from logs, and enforcing a max payload with truncation metadata.

Suggested PRD patch
 ## Error Handling
@@
 - The upload itself remains fatal (matching existing behavior in `executeMainTerraformCommand`).

+## Security and Payload Constraints
+
+- Treat `ci.outputs` and `ci.output_log` as potentially sensitive.
+- Never upload values marked sensitive by terraform metadata; mask as `"[REDACTED]"` (or omit).
+- Apply log scrubbing before base64 encoding (credentials, tokens, secrets).
+- Enforce a maximum encoded size for `ci.output_log` (for example, 256KB or 1MB), truncating safely when exceeded.
+- Include truncation metadata (e.g., `output_log_truncated: true`) so the server/UI can signal partial logs.

Also applies to: 181-193, 241-245, 255-256

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/prd/pro-summary-upload.md` around lines 59 - 63, Update the PRD to
require explicit secret-redaction and payload-size limits for the CI output
fields: enforce that ci.outputs and the OutputLog (json:"output_log", referenced
as OutputLog) must have sensitive values masked or dropped (e.g., remove tokens,
credentials, secrets), include a description of the redaction strategy (masking
pattern or drop-on-detect) and add a max payload size limit with behavior on
overflow (truncate output, include truncation metadata and byte counts). Also
apply the same requirements to the other CI output sections noted (the other
ci.outputs/ci.output_log occurrences) so all mentions include the redaction
rule, truncation policy, and metadata requirements.

Comment on lines +133 to +140
2. Call `terraform.ParseOutput()` on the captured command output to get the `OutputResult`.
3. Build an `InstanceStatusCI` struct and map the parsed result:
- `HasChanges` ← `result.HasChanges`
- `HasErrors` ← `result.HasErrors`
- `ResourceCounts` ← `result.Data.(*TerraformOutputData).ResourceCounts`
- `Outputs` ← `result.Data.(*TerraformOutputData).Outputs` (apply only, convert `TerraformOutput.Value` to raw values)
- `Warnings` ← `result.Data.(*TerraformOutputData).Warnings`
- `Errors` ← `result.Errors`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify how ParseOutput and OutputResult.Data are defined and used.
rg -n -C3 --type go '\bfunc\s+ParseOutput\s*\('
rg -n -C3 --type go '\btype\s+OutputResult\s+struct\b|\bData\s+.*\b'
rg -n -C3 --type go '\btype\s+TerraformOutputData\s+struct\b'
rg -n -C3 --type go 'Data\.\(\*TerraformOutputData\)'

Repository: cloudposse/atmos

Length of output: 26893


Update PRD to reflect safe type assertion pattern.

The PRD snippet shows a direct type assertion without checking success, which could panic. The actual codebase (e.g., pkg/ci/plugins/terraform/plugin.go:133) uses safe assertions with ok checks when accessing result.Data. Update the PRD to document this proper pattern:

Suggested PRD patch
3. Build an `InstanceStatusCI` struct and map the parsed result using a safe cast:
+   - `tfData, ok := result.Data.(*TerraformOutputData)`; if `!ok`, log warning and skip `ci` enrichment
    - `HasChanges` ← `result.HasChanges`
    - `HasErrors` ← `result.HasErrors`
-   - `ResourceCounts` ← `result.Data.(*TerraformOutputData).ResourceCounts`
-   - `Outputs` ← `result.Data.(*TerraformOutputData).Outputs` (apply only, convert `TerraformOutput.Value` to raw values)
-   - `Warnings` ← `result.Data.(*TerraformOutputData).Warnings`
+   - `ResourceCounts` ← `tfData.ResourceCounts`
+   - `Outputs` ← `tfData.Outputs` (apply only, convert `TerraformOutput.Value` to raw values)
+   - `Warnings` ← `tfData.Warnings`
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/prd/pro-summary-upload.md` around lines 133 - 140, The PRD shows an
unsafe direct type assertion on result.Data (e.g.,
result.Data.(*TerraformOutputData).Outputs) which can panic; update the steps
that map ParseOutput()'s OutputResult into InstanceStatusCI to use a safe
assertion pattern: call terraform.ParseOutput(), then check the assertion like
data, ok := result.Data.(*TerraformOutputData) and only read
data.ResourceCounts, data.Outputs (converting TerraformOutput.Value to raw
values), and data.Warnings when ok is true, otherwise set Defaults/empty values
and propagate result.Errors into InstanceStatusCI.Errors; mention the use of the
ok boolean and fallback behavior when mapping HasChanges, HasErrors,
ResourceCounts, Outputs, Warnings, and Errors.

@codecov
Copy link

codecov bot commented Mar 26, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.26%. Comparing base (2be2909) to head (ecbc4cc).

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main    #2259      +/-   ##
==========================================
+ Coverage   77.21%   77.26%   +0.04%     
==========================================
  Files        1018     1018              
  Lines       96368    96368              
==========================================
+ Hits        74415    74457      +42     
+ Misses      17755    17712      -43     
- Partials     4198     4199       +1     
Flag Coverage Δ
unittests 77.26% <ø> (+0.04%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 9 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-release Do not create a new release (wait for additional code changes) size/m Medium size PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant