Skip to content

Home

Jump to bottom
karlderkaefer edited this page Dec 12, 2025 · 1 revision

cdk-notifier Wiki

Go-based CLI for notifying code hosting providers (GitHub, GitLab, Bitbucket) using configurable inputs and templated transformations.

Table of Contents

Source Files (8)
  • main.go
  • cmd/root.go
  • config/app.go
  • provider/api.go
  • provider/github.go
  • provider/gitlab.go
  • provider/bitbucket.go
  • transform/transformer.go

Architecture Overview

This CLI ingests CDK deployment logs, summarizes meaningful changes, and posts a single, maintained comment to a pull/merge request. Configuration is assembled from flags and environment variables, then normalized into an application config. A transformer extracts and formats changes, optionally suppressing noise (e.g., hash-only updates). A provider-agnostic notifier interface selects the correct VCS (GitHub, GitLab, Bitbucket) and reconciles comments (create, update, or delete) based on detected changes.

Runtime Flow

  • Entry: main.go delegates to cmd/root.go (Cobra command).
  • Config: config/app.go initializes settings from flags/env and validates required inputs (repo, owner, token, PR/MR ID).
  • Transform: transform/transformer.go parses CDK logs, builds final comment content, and tracks change counts for suppression logic.
  • Notify: provider/api.go selects a provider and posts or updates the PR/MR comment; skips posting when disabled or when only suppressed changes exist.

Configuration & Inputs

  • CLI flags: cmd/root.go defines repo/owner, token, PR/MR ID, log file, tag ID, and verbosity.
  • Environment variables: config/app.go maps common CI variables and tokens; supports hosted and enterprise/URL overrides.
  • Behavior toggles: no-post mode, force delete, collapse/overview settings, and hash-change suppression (regex-based).
  • Validation: early exit with clear warnings when critical inputs (e.g., PR/MR ID) are missing.

Providers & Abstraction

  • Abstraction: provider/api.go defines NotifierService (create, update, delete, list, post comment) and a consistent header/tag for idempotent updates.
  • GitHub: provider/github.go implements comment operations and enforces provider-specific limits.
  • GitLab: provider/gitlab.go maps to notes and project endpoints with size limits.
  • Bitbucket: provider/bitbucket.go (and related client) handles Bitbucket API specifics behind the same interface.
flowchart TD
    A[CLI entry] --> B[Load config]
    B --> C[Parse logs]
    C --> D[Choose provider]
    D --> E[Call API]
    E --> F[Post comment]
Loading

Why this design:

  • Clear separation of concerns: command wiring, configuration, transformation, and provider integration live in focused packages.
  • Pluggable providers: a single interface (provider/api.go) enables consistent behavior across VCS systems.
  • Idempotent commenting: stable header/tag allows safe updates or deletions without duplicating information.
  • CI-friendly: flags and env mapping make the tool easy to embed in diverse pipelines.
Source Files (7)
  • provider/api.go
  • provider/github.go
  • provider/gitlab.go
  • provider/bitbucket.go
  • transform/transformer.go
  • transform/template.go
  • config/app.go

Design Patterns & Conventions

This project organizes notification delivery as a configuration-driven pipeline. Logs are cleaned and summarized, then rendered with templates before being posted to a chosen VCS provider. Clear separation of concerns keeps transformation independent from transport. Interfaces and dependency injection enable mocking and provider swapping without changing core logic.

Core Patterns by Component

  • Provider Strategy (provider/*.go): Each VCS (GitHub, GitLab, Bitbucket) is a pluggable strategy responsible for posting comments and enforcing API limits. Shared contracts and clients encapsulate API specifics.
  • Chain of Responsibility (transform/transformer.go): Line processors operate sequentially to clean ANSI/color codes, normalize diff markers, compute metrics, and apply truncation. Each processor focuses on a single concern.
  • Template Rendering (transform/template.go): Default and extended templates format content consistently. VCS behaviors (e.g., collapsible sections) are parameterized and driven by configuration.

Conventions & Boundaries

  • Package layout: config/ (inputs and defaults), transform/ (content processing), provider/ (VCS integrations). Keep transforms stateless and free of provider logic.
  • Interfaces & DI: Providers expose narrow interfaces for notes/comments and projects. Tests use mocks to validate behavior without network calls.
  • API limits: Each provider defines a max comment length; transformers truncate with a visible warning rather than failing. Limits differ per VCS and are set conservatively.
  • Presentation rules: Collapsible sections are enabled for providers that render them well, and can be disabled via flags. Templates use minimal markup for portability.

Testing & Reliability

  • Deterministic outputs: Tests verify cleaning, header creation, truncation, and provider selection with fixed inputs and expectations.
  • Robustness: Strip ANSI sequences and non-printable characters to guarantee readable diffs across VCS UIs.
  • Logging: Consistent log levels with contextual messages (e.g., when truncation occurs) aid troubleshooting.
  • Config-driven behavior: config/app.go centralizes options (VCS, tokens, toggles) so runtime changes do not require code changes.

Mermaid (validated)

flowchart TD
    A[Config] --> B[Transformer]
    B --> C[Template]
    C --> D[Provider Strategy]
    D --> E[VCS API]
Loading
Source Files (4)
  • config/app.go
  • config/app_test.go
  • cmd/root.go
  • main.go

Configuration & Setup

This project reads configuration from CLI flags and environment variables to assemble a NotifierConfig, then processes a CDK log and posts a comment to a pull/merge request. The entrypoint main.go delegates to Cobra in cmd/root.go, which initializes config (config/app.go), runs the transformer, and invokes a provider to post to the selected VCS. Configuration is designed to be CI-friendly: it gracefully handles missing IDs, supports multiple CI/VCS systems, and can suppress noisy hash-only changes.

Configuration Sources

  • config/app.go: NotifierConfig.Init merges CLI flags, env vars, and defaults using Viper.
  • CI-aware env detection for PR/MR IDs, repo/owner, tokens; supports CircleCI, Bitbucket, GitLab, GitHub (incl. Enterprise host).
  • Safe defaults: missing PR/MR ID logs a warning and skips posting; other fields remain valid.
  • config/app_test.go: validates env precedence, CI/VCS overrides, templates, and host extraction.

CLI & Environment Mapping

  • cmd/root.go defines flags for repo, owner, token, pull-request-id, log-file, tag-id, template, custom-template.
  • Viper maps env keys to flags (e.g., REPO_NAME→repo, PR_ID→pull-request-id, TOKEN→token).
  • Additional controls: suppress-hash-changes (+ regex), delete/no-post-mode, disable-collapse, show-overview.
  • Verbosity via persistent flag sets log level (debug→panic).

CI/VCS Selection & Posting

  • CI system and VCS set via flags or env (e.g., CircleCI, Bitbucket, GitLab, GitHub/GHE).
  • Provider creation chooses the correct API client and authentication based on NotifierConfig.
  • NoPostMode halts posting; missing PR/MR ID triggers a warning and skip to avoid misposts.
  • SuppressHashChanges can auto-force deletion when only hash changes are detected.

Templates & Content

  • Template selection via template or custom-template; content rendered from transformer output.
  • transform processes log file into concise comment text, optionally adds overview stats.
  • TagID identifies stack context in multi-stack pipelines.

Mermaid: Startup & Posting Flow

graph TD
    A[Main] --> B[Root Cmd]
    B --> C[Config Init]
    C --> D[Transform]
    D --> E[Notifier]
    E --> F[VCS API]
Loading

Edit in Mermaid Chart Playground

Diagram shows how the app starts, initializes config, transforms logs, creates a notifier, and posts to the selected VCS API.

Source Files (6)
  • provider/api.go
  • provider/api_test.go
  • provider/github.go
  • provider/gitlab.go
  • provider/bitbucket.go
  • provider/bitbucket_client.go

Public Interfaces: Provider API

The Provider API defines a unified, public interface for posting, updating, and deleting comments on pull/merge requests across GitHub, GitLab, and Bitbucket. It standardizes operations via the NotifierService in provider/api.go, while each provider-specific client wraps the upstream SDKs and exposes only the required methods. The API focuses on a tagged comment lifecycle: discover existing comments, decide whether a diff warrants changes, and perform create/update/delete consistently. This abstraction keeps CI integrations portable and minimizes vendor-specific logic.

Core Interface (provider/api.go)

  • NotifierService methods: CreateComment, UpdateComment, DeleteComment, Set/GetCommentContent, PostComment, ListComments.
  • CommentOperation enum: CREATED, UPDATED, DELETED, NOTHING; used to report outcomes.
  • Comment model: Id, Body, Link; provider responses transform to this neutral type.
  • Tagging and detection: HeaderPrefix and TagID identify managed comments; diffHasChanges checks if a diff contains actionable changes.

Provider Clients

  • GitHub (provider/github.go): GithubClient with GithubIssuesService; enforces max comment length (65536); OAuth and context support.
  • GitLab (provider/gitlab.go): GitlabClient with Notes/Projects services; generous max length (1,000,000); works on merge request notes.
  • Bitbucket (provider/bitbucket.go, provider/bitbucket_client.go): BitbucketProvider with BitbucketRepositoryService; base URL v2 API; max length 32768.
  • Each client reads config.NotifierConfig (token, repo/project refs, PR/MR IDs, TagID) and sets Comment/Note content via SetCommentContent.

Behavior and Defaults

  • PostComment orchestrates: list existing, find tag, decide create/update/delete based on diff and config.
  • Returns a CommentOperation, not raw HTTP details, for stable CI reporting.
  • User agent: “cdk-notifier”; consistent logging across providers.
  • Error handling aligns to each SDK; tests cover unauthorized and no-token cases.
sequenceDiagram
participant Caller
participant Notifier
participant Provider
participant VCS
Caller->>Notifier: Post comment
Notifier->>Provider: List comments
Provider->>VCS: GET comments
VCS-->>Provider: Comments
Provider-->>Notifier: Has tag?
alt Diff changes
Notifier->>Provider: Create/Update/Delete
Provider->>VCS: Write comment
VCS-->>Provider: Result
Provider-->>Notifier: Operation
else No changes
Notifier-->>Caller: Nothing
end
Loading
Source Files (4)
  • provider/github.go
  • provider/github_test.go
  • provider/api.go
  • config/app.go

Providers: GitHub Integration

This provider posts and manages pull request comments on GitHub. It supports both GitHub.com and GitHub Enterprise via configuration, using an OAuth token for authentication. The client wraps the GitHub Issues API to list, create, edit, and delete comments and transforms API responses into an internal, provider-agnostic Comment model. Comment behavior (create vs. update/delete) is driven by config flags and tags, with safe handling of the GitHub comment length limit (65,536 chars).

Configuration (config/app.go)

  • Select VCS: GitHub or GitHub Enterprise; host is parsed from CI (e.g., CircleCI).
  • Requires token; validated from env (e.g., GITHUB_TOKEN). Missing token yields a validation error.
  • PullRequestID, RepoOwner, RepoName resolved from CI and config fields.
  • Template and DeleteComment flags influence content and lifecycle.

Client & Services (provider/github.go)

  • NewGithubClient builds an authenticated client using the configured token.
  • Enterprise mode uses host-specific REST endpoints; otherwise defaults to GitHub.com.
  • IssuesService is set for comment operations (list, create, edit, delete).
  • IssueComment objects are transformed to an internal Comment (id, body, link).

Comment Lifecycle (provider/api.go, provider/github.go, provider/github_test.go)

  • PostComment: list existing comments; update/delete tagged content or create a new comment.
  • TagID identifies managed comments; DeleteComment toggles cleanup behavior.
  • Returns a sentinel “no action” value when nothing is posted; surfaces API errors from GitHub.
  • Tests cover missing token flows and mocked IssuesService behavior.
sequenceDiagram
    participant App
    participant GHClient as GithubClient
    participant Issues as IssuesService
    participant GH as GitHub API
    App->>GHClient: PostComment
    GHClient->>Issues: ListComments
    alt Update/Delete
        Issues->>GH: GET comments
        GHClient->>Issues: Edit/Delete
    else Create
        GHClient->>Issues: CreateComment
        Issues->>GH: POST comment
    end
Loading
Source Files (4)
  • provider/gitlab.go
  • provider/gitlab_test.go
  • provider/api.go
  • config/app.go

Providers: GitLab Integration

This provider posts CDK notifier output to GitLab Merge Requests as MR notes. It wraps the official GitLab client and exposes a small surface for listing, creating, updating, and deleting notes tied to a specific project and merge request. Configuration is centralized via NotifierConfig, enabling environment-driven setup across CI systems. The provider avoids duplicate comments by tagging content and only updates when changes are detected. It also no-ops when no differences are found and respects GitLab’s maximum comment length.

Key Components (provider/gitlab.go)

  • GitlabClient: Holds GitLab services (Notes, Projects), context, client instance, NotifierConfig, ProjectId cache, and NoteContent.
  • NotesService and ProjectsService: Narrow interfaces for required GitLab API calls (list/create/update/delete notes, fetch project).
  • Project discovery: Resolves and caches ProjectId from repo owner/name to minimize API calls.
  • Comment normalization: Converts GitLab notes to internal comment objects for consistent handling across providers.

Behavior & Lifecycle (provider/api.go, provider/gitlab.go)

  • List existing notes, locate the tagged comment, and decide to update or create.
  • No-op when there are no detected changes in the rendered diff; return “nothing” status.
  • Enforces platform limits (e.g., GitLab max note length) before posting.
  • Optional cleanup: delete or update older tagged notes based on config.

Configuration & CI Integration (config/app.go, provider/gitlab_test.go)

  • NotifierConfig: Supplies token, base URL, repo owner/name, merge request ID, tag ID, and flags (e.g., delete-on-update).
  • CI-derived values: Repo, MR/Pull Request IDs, and tokens are read from standard env vars; supports GitLab SaaS and self-managed via base URL.
  • Failure handling: On missing/invalid credentials or IDs, PostComment returns a no-op with an error; tests cover these paths.
  • Consistency with other providers: Shares the common provider API to keep behavior uniform across GitHub/Bitbucket/GitLab.

Outcomes & Guarantees

  • Single authoritative comment: Tagged note is created once and updated thereafter.
  • Clear statuses: Create, update, delete, or no-op results surface to callers.
  • Scalable calls: ProjectId caching and targeted note queries reduce API round-trips.
  • Safe by default: If no diff changes are detected, nothing is posted.
sequenceDiagram
  participant App
  participant Client
  participant API
  participant Notes
  App->>Client: Init with config
  Client->>API: Get project
  API-->>Client: Project ID
  Client->>Notes: List notes
  alt has changes
    Client->>Notes: Create/Update note
  else no changes
    Client->>App: No action
  end
  Notes-->>Client: Result
  Client-->>App: Operation status
Loading
Source Files (5)
  • provider/bitbucket.go
  • provider/bitbucket_client.go
  • provider/bitbucket_test.go
  • provider/api.go
  • config/app.go

Providers: Bitbucket Integration & Client

The Bitbucket provider integrates pull request commenting into the notifier by wrapping the Bitbucket Cloud REST API (v2.0). It separates orchestration (provider) from transport (client), exposing a small service interface that is easy to test and mock. Configuration is driven by NotifierConfig (repo, PR, token, tag), enabling idempotent comment management across CI environments. The design focuses on predictable operations (create, update, delete, no-op) and safe limits (comment length), while surfacing clear error states (e.g., unauthorized).

Components & Files

  • provider/bitbucket.go: BitbucketProvider orchestrates operations and transforms BitbucketComment to internal Comment; enforces BitbucketMaxCommentLength.
  • provider/bitbucket_client.go: BitbucketClient handles HTTP, BaseURL (https://api.bitbucket.org/2.0/), and exposes Repositories via IBitbucketRepositoryService (list/create/edit/delete).
  • provider/api.go: Defines shared comment model and CommentOperation results (CREATED, UPDATED, DELETED, NOTHING) used by providers.
  • provider/bitbucket_test.go: Mocks repository service to validate flows (list, create, edit, delete) and error handling (e.g., 401 unauthorized).

Configuration & Auth

  • config/app.go: NotifierConfig provides Token/TokenUser, RepoOwner, RepoName, PullRequestID, Vcs, TagID; CI env can override values for Bitbucket runs.
  • NewBitbucketProvider uses NotifierConfig to initialize the client and bind the Repositories service; context defaults to background if nil.
  • Authentication uses the provided token; invalid or missing tokens yield explicit API errors (e.g., 401 Unauthorized).
  • TagID enables scoping and de-duplicating comments across runs.

Comment Operations & Behavior

  • List existing PR comments, detect tagged comment, and decide the operation:
    • Create when no tagged comment exists and content is relevant.
    • Update when a tagged comment exists and content changed.
    • Delete when content indicates no differences and cleanup is enabled.
    • No-op when nothing meaningful changed.
  • Provider enforces maximum comment length before submission.
  • Service interface abstracts Bitbucket API, keeping provider logic testable and transport-agnostic.
  • Errors reflect API responses and validation (e.g., empty content), supporting clear status in CI logs.

Sequence: Comment Posting

sequenceDiagram
    participant App
    participant Provider
    participant Client
    participant Bitbucket
    App->>Provider: Post comment
    Provider->>Client: Build request
    Client->>Bitbucket: API call
    Bitbucket-->>Client: Response
    Client-->>Provider: Comment info
    Provider-->>App: Operation result
Loading
Source Files (5)
  • transform/transformer.go
  • transform/template.go
  • transformer/transformer_test.go
  • transform/template_test.go
  • config/app.go

Templating & Transformation Engine

This engine converts CDK diff output into clean, VCS-friendly comments. It removes terminal formatting, normalizes changes into readable “diff” blocks, and applies a selectable template for context and metadata. Provider-aware behavior (e.g., GitHub collapsible sections and comment length limits) ensures reliable posting. Metrics such as total changes and replacements are summarized to help reviewers quickly assess impact.

Processing Pipeline

  • LogTransformer (transform/transformer.go) orchestrates reading, cleaning, transforming, templating, and truncation.
  • ANSI color codes are stripped to prevent unreadable artifacts in comments.
  • Diff symbols are normalized to Markdown diff format for consistent rendering.
  • Final content is truncated per VCS limits (e.g., GitHub/GHE), adding a warning if shortened.

Templates & Rendering

  • Templates live in transform/template.go and are selected via Template/CustomTemplate.
  • Default, Extended, and Extended-with-Resources strategies expose different levels of context.
  • Template fields include TagID, JobLink, HeaderPrefix, Collapsible, and summary metrics.
  • GitHub comments can be collapsible; behavior is configurable (DisableCollapse, ShowOverview).

Configuration & Provider Constraints

  • NotifierConfig (config/app.go) passes TagID, VCS, log file path, and behavior flags.
  • Provider-specific rules drive collapsible sections and max comment length.
  • Optional suppression of hash-only changes via regex reduces noise.
  • Tests (transform/transformer_test.go, transform/template_test.go) validate removal of ANSI codes, header formatting, overview rendering, and truncation behavior.
graph TD
  C[Config] --> T[LogTransformer]
  T --> A[Strip ANSI]
  A --> D[Transform Diff]
  D --> H[Apply Template]
  H --> O[Comment]
Loading
Source Files (4)
  • config/app.go
  • provider/api.go
  • provider/bitbucket_client.go
  • transform/template.go

Data Models & Validation

This project standardizes how CDK diff output becomes a VCS-ready comment. Core models in config/app.go capture runtime inputs and enforce required values before any API calls. The transform layer maps raw logs into a structured message with safe formatting and provider-aware limits. Provider clients encapsulate API behaviors and comment-size constraints so validation is consistent and predictable across GitHub, GitLab, and Bitbucket.

Core Models

  • Configuration: NotifierConfig (config/app.go) loads CLI/env, normalizes defaults, and validates mandatory fields (for example, pull request/merge request IDs).
  • Transformation: LogTransformer (transform/transformer.go) stores input content, metrics (TotalChanges, HashChanges), provider flags (Vcs, DisableCollapse, NoPostMode), and size limits (e.g., GithubMaxCommentLength).
  • Providers: API abstractions (provider/api.go) define a unified notifier interface; specific clients implement comment list/create/update/delete. Bitbucket client types live in provider/bitbucket_client.go; GitLab limits include GitlabMaxCommentLength.

Validation & Constraints

  • Config validation: Initial checks in config/app.go prevent posting with missing identifiers; the command exits early rather than failing late.
  • Content sanitization: Transformer strips ANSI sequences and converts additions/removals into a Markdown diff-safe format to avoid broken rendering.
  • Size enforcement: Provider-aware truncation guarantees comments never exceed API limits (e.g., GitHub vs. GitLab). When truncation occurs, a warning banner is injected so reviewers know content was shortened.
  • Change filtering: If “suppress hash changes” is enabled and only hash diffs are detected, posting is skipped and existing provider comments may be deleted to reduce noise.

Presentation Rules (Templates)

  • Templates: Default and extended templates in transform/template.go render a stable header, diff code block, and optional overview (NumberOfDifferencesString, NumberReplaces).
  • Collapsible sections: For GitHub, diffs render inside a collapsible section unless DisableCollapse is set. Bitbucket and unspecified VCS render non-collapsible content.
  • Idempotent updates: Providers reconcile by tag/marker to create, update, or delete comments based on current content and policy, ensuring a single authoritative thread per PR/MR.

Mermaid diagram

flowchart TD
  A[Config Init] --> B[Transform Log]
  B --> C[Render Template]
  C --> D{Length OK?}
  D -- No: truncate --> C
  D -- Yes --> E[Prepare Comment]
  E --> F[VCS API]
Loading

Why this matters

  • Clear boundaries separate config validation, content normalization, and provider posting.
  • Deterministic size checks and filtering prevent noisy or rejected comments.
  • Simple, explicit templates yield consistent reviewer experiences across providers.
Source Files (5)
  • main.go
  • cmd/root.go
  • transform/transformer.go
  • provider/api.go
  • config/app.go

CLI Usage & Execution Workflow

This CLI reads infrastructure diff logs, formats them for review, and optionally posts a summary to a pull/merge request. Execution is driven by a single root command that initializes configuration, transforms raw logs into concise markdown, and applies posting rules. Guards ensure harmless runs (e.g., dry runs or hash-only diffs) and safe exits when required context, such as a PR ID, is missing.

Command Entry & Dispatch

  • main.go starts the application and calls the root command.
  • cmd/root.go defines the CLI, wires flags/env, and orchestrates the run.
  • The run sequence: initialize config, process logs, evaluate guards, then (optionally) notify a provider.
  • Errors are fatal where continuation would mislead (e.g., invalid provider setup).

Configuration & Guards

  • config/app.go builds NotifierConfig from flags and environment, validates critical inputs (e.g., PR ID).
  • Hash-change suppression: if only hash changes are detected, posting is skipped and comment deletion may be forced.
  • No-post mode enables transformation without any remote side effects.
  • Provider posting proceeds only when conditions pass (not suppressed, PR ID present, not in no-post).

Log Transformation & Notifier

  • transform/transformer.go cleans ANSI/color, normalizes signs, and formats output as markdown diff.
  • It creates a compact header, counts changes, and truncates content to provider limits.
  • provider/api.go picks the correct VCS notifier, sets the rendered content, and posts a single comment to the target PR/MR.
sequenceDiagram
    participant CLI
    participant RootCmd
    participant Transformer
    participant Provider
    CLI->>RootCmd: execute
    RootCmd->>RootCmd: init config
    RootCmd->>Transformer: process logs
    Transformer-->>RootCmd: summary
    RootCmd->>RootCmd: checks (suppress/no-post/PR)
    alt post allowed
        RootCmd->>Provider: create notifier
        Provider->>Provider: set content
        Provider->>Provider: post comment
    else skip
        RootCmd->>RootCmd: exit
    end
Loading
Source Files (7)
  • config/app_test.go
  • provider/api_test.go
  • provider/github_test.go
  • provider/gitlab_test.go
  • provider/bitbucket_test.go
  • transform/template_test.go
  • transform/transformer_test.go

Testing & Quality Assurance

Our tests ensure that configuration, transformation, and provider integrations produce correct, reviewable outputs without leaking invalid comments to VCS. They validate environment-driven configuration, comment lifecycle decisions, and safe handling of tokens and API limits. Provider suites assert idempotent behavior based on tags and diff content. Transformation tests guard content accuracy and truncation, while factory tests confirm the correct client is created or rejected.

What We Test (by area)

  • Configuration (config/app_test.go): Merges env variables into NotifierConfig, detects CI/VCS flavor (including GitHub Enterprise host), parses PR IDs, and respects user-provided template settings.
  • Providers (provider/github_test.go, provider/gitlab_test.go, provider/bitbucket_test.go): Verify tokenless/unauthorized paths return “nothing posted,” and that create/update/delete decisions follow tag and diff signals. Bitbucket includes end-to-end flows guarded by tokens.
  • Service Factory and Diff Gate (provider/api_test.go): Ensures unsupported VCS is rejected, correct client types are returned for supported VCS, and the diff gate recognizes meaningful changes.
  • Transformation (transform/template_test.go, transform/transformer_test.go): Validates overview sections, change/replacement counts, resource tallies, and safe truncation with provider-specific length limits and visible warnings when exceeded.

Quality Gates and Behaviors

  • Diff gate: Only posts when meaningful changes are detected; otherwise exits with “no post.”
  • Comment lifecycle: Uses tag-based matching to create once, update when content changes, and delete when diffs disappear.
  • Robust error handling: Unauthorized or missing tokens return explicit errors and avoid posting.
  • Size safety: Truncates overly long outputs per provider limits, appending a clear warning to preserve readability.

Test Strategy and Signals

  • Fast unit focus: Heavy use of mocks for GitHub/GitLab/Bitbucket services to keep feedback quick and deterministic.
  • Opt-in integration: Real API tests run only when tokens are present, otherwise are skipped to keep CI reliable.
  • Clear assertions: Type- and value-level checks for errors, no-op outcomes, and expected comment operations.
  • Maintainability: Tests mirror production boundaries—config ingest, transform, provider API—making failures actionable.

Mermaid diagram

flowchart TD
  A[CI Config] --> B[Transform Logs]
  B --> C{Diff changes?}
  C -- Yes --> D[Provider Client]
  D --> E[VCS Comment]
  C -- No --> F[No Post]
Loading
Source Files (4)
  • tools.go
  • main.go
  • cmd/root.go
  • config/app.go

Build, Deployment & Operations

This CLI processes CDK logs and posts concise change summaries to pull requests across supported VCS providers. The execution starts in main.go, routes into cmd/root.go, loads configuration from flags and environment (config/app.go), then transforms logs and posts a comment via the provider layer. Operations focus on predictable runs in CI, noise reduction (e.g., hash-change suppression), and safe fallbacks like dry-run mode. The design favors simple builds, portable configuration, and clear operational controls.

Build & Packaging

  • main.go is the entrypoint; it invokes cmd.Execute() to run the CLI.
  • tools.go uses the “tools” build tag to vendor developer tooling without shipping it in the runtime binary.
  • Standard Go builds produce a single static CLI, minimizing external dependencies.
  • Goal: deterministic builds and straightforward distribution within CI pipelines.

Configuration & Inputs

  • config/app.go initializes NotifierConfig, merging CLI flags with environment via viper mappings.
  • cmd/root.go defines core flags (repo, owner, token, PR ID, log-file, tag-id) and behavior flags (template, suppress-hash-changes, no-post-mode).
  • PR ID is validated; GitHub Enterprise host can be derived from PR URL; tokens are sourced per VCS.
  • Why: consistent, portable configuration across CircleCI, Bitbucket Pipelines, GitLab CI, and GitHub Actions.

Deployment & Operations

  • Typical usage: run after a CDK diff job; transformer summarizes changes and prepares comment content.
  • Noise control: suppress-hash-changes reduces churn-only updates; ForceDeleteComment removes stale comments if only hashes changed.
  • Posting: provider selection is based on VCS flags; no-post-mode prints diff and writes artifacts instead of posting.
  • Observability: verbosity control via -v; warnings logged when configuration is incomplete.
graph TD
  A[CLI run] --> B[Load config]
  B --> C[Transform logs]
  C --> D{No post?}
  D -- Yes --> E[Print diff]
  D -- No --> F[Post via VCS]
Loading

Edit in Mermaid Chart Playground

Clone this wiki locally