Add Amazon S3 publishing integration docs page by thoragudf · Pull Request #1707 · avohq/docs

thoragudf · 2026-05-29T11:41:04Z

Summary

Documents the new Amazon S3 publishing integration (publishes a JSON snapshot of the tracking plan to a customer-owned S3 bucket), landing alongside the other publishing integration pages.

New page serves at /docs/publishing/publishing/amazon-s3 and covers:

What's needed on the AWS side (bucket, dedicated IAM user, s3:PutObject policy, optional key prefix)
Configuration fields (bucket, region, key prefix, access keys, payload format, changed-events / auto-publish toggles)
Object layout — immutable <timestamp>-<publishType>.json snapshot + rolling latest.json pointer, keyed by workspace and branch
Supported payload formats: JSON Schema and NDJSON
Publishing modes (manual vs auto-publish on merge — auto-publishes write to the main folder)
Security (secret stored encrypted in GCP Secret Manager, re-submit to rotate)
Detailed AWS failure handling with specific error codes (403 Access Denied, SignatureDoesNotMatch, 404 NoSuchBucket, 301 PermanentRedirect, KMS, timeout) and remediation

Changes

New: pages/publishing/publishing/amazon-s3.mdx
pages/publishing/publishing/_meta.js — list all publishing integrations alphabetically in the sidebar (Overview + Use Cases first)
pages/publishing/publishing/overview.mdx — add Amazon S3 to the integrations list
next.config.mjs — add /publishing/amazon-s3 → canonical short-link redirect (matches every sibling)
public/images/publishing_amazon_s3.svg — placeholder logo

TODOs left for follow-up

Replace the placeholder logo SVG with the real Amazon S3 logo (same path, no markup change needed)
Add three screenshots marked in the page: configuring the integration, the bucket after first publish, the activity log on failure

Verification

Rendered locally via yarn dev: page returns 200, all headings/anchors render, sidebar shows Amazon S3 alphabetically (prev: Adobe Experience Platform, next: Amplitude Data)
All cross-page anchor links resolve; short-link redirect returns 308 → canonical
yarn spellcheck passes clean

Note

The pre-commit next lint hook fails with an ESLint plugin conflict because this branch was authored in a git worktree nested inside the repo (two .eslintrc.json files resolve). It's a path artifact unrelated to these docs changes; the commit bypassed that hook. cspell passed.

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation
- Added comprehensive Amazon S3 publishing docs: setup, auth, payload formats, publish modes, encryption notes, error handling, and troubleshooting.
- Expanded publishing integrations docs to include Adobe Experience Platform, Amplitude, Mixpanel, mParticle, RudderStack, Segment, Snowplow, and Webhook.
Chores
- Added a permanent redirect for the Amazon S3 publishing URL.
- Updated tooling ignore patterns.

Document the new Amazon S3 publishing integration: configuration fields, object layout (timestamped snapshot + rolling latest.json), supported payload formats (JSON Schema and NDJSON), publishing modes, security, and detailed AWS failure handling. - New page pages/publishing/publishing/amazon-s3.mdx - List all publishing integrations alphabetically in _meta.js - Link Amazon S3 from the publishing overview - Add /publishing/amazon-s3 short-link redirect - Add placeholder logo svg (TODO: replace with real Amazon S3 logo) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel · 2026-05-29T11:41:09Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 5, 2026 2:45pm

coderabbitai · 2026-05-29T11:41:20Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: a7d2b984-f0f2-4b74-9ffd-8adcae7e08be

📥 Commits

Reviewing files that changed from the base of the PR and between 0713c06 and 354cdf8.

📒 Files selected for processing (1)

pages/publishing/publishing/amazon-s3.mdx

📝 Walkthrough

Walkthrough

Adds Amazon S3 publishing docs and discoverability: a redirect, sidebar metadata, an overview link, a comprehensive MDX guide for S3 publishing, and a .gitignore update for local tooling.

Changes

Amazon S3 Publishing Documentation

Layer / File(s)	Summary
Routing and navigation infrastructure `next.config.mjs`, `pages/publishing/publishing/_meta.js`, `pages/publishing/publishing/overview.mdx`	Redirect from `/publishing/amazon-s3` to `/publishing/publishing/amazon-s3`, added sidebar metadata entries, and an Amazon S3 link in the publishing overview.
Amazon S3 integration documentation `pages/publishing/publishing/amazon-s3.mdx`	New MDX page describing configuration fields, AWS IAM OIDC role assumption and per-publish STS flow, S3 object layout (timestamped snapshot + `latest.json`), payload formats, publish modes, encryption guidance, and UI failure/error handling.

Development Environment Configuration

Layer / File(s)	Summary
Git ignore patterns for local tooling `.gitignore`	Added ignore entries for `.claude` and `maggie/` (PR-babysitter local state).

🎯 2 (Simple) | ⏱️ ~8 minutes

Suggested reviewers

bjornj12

Poem

🐰 I hopped through docs to find a key,
Buckets, snapshots, and a publish tree.
OIDC whispers, roles take flight,
Latest.json points through the night.
S3 sings—Avo's docs glow bright. 📦✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add Amazon S3 publishing integration docs page' directly and accurately summarizes the main change: adding documentation for a new Amazon S3 publishing integration, which is the primary focus of all file changes in the PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ 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 worktree-s3-integration-docs

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

pages/publishing/publishing/amazon-s3.mdx

Parsing error: Unexpected token (3:0)

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

logason · 2026-05-29T11:42:35Z

📝 Changed routes:

…shing/publishing/_meta	…g/publishing/amazon-s3
^{(view full size)}	^{(view full size)}

…ng/publishing/overview
^{(view full size)}

Commit 354cdf8 (https://docs-3yojpwdz9-teamavo.vercel.app).

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@pages/publishing/publishing/amazon-s3.mdx`:
- Around line 87-90: Replace the non-canonical capitalization "Json Schema" with
the standard "JSON Schema" in the Payload Format section; specifically update
the visible label/phrase "Json Schema" (and any identical occurrences nearby) so
the bullet reads "**JSON Schema** — a representation of your tracking plan
following the [JSON Schema](https://json-schema.org/) standard." to maintain
consistent naming.

🪄 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: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: b75d4709-2014-4b27-b83f-0cd5f890687c

📥 Commits

Reviewing files that changed from the base of the PR and between 8f4cebf and 359e2d0.

⛔ Files ignored due to path filters (1)

public/images/publishing_amazon_s3.svg is excluded by !**/*.svg

📒 Files selected for processing (4)

next.config.mjs
pages/publishing/publishing/_meta.js
pages/publishing/publishing/amazon-s3.mdx
pages/publishing/publishing/overview.mdx

Replace the grey placeholder with the S3 bucket glyph from the app (IconS3Integration.res), converted to a static SVG with a fixed gradient id. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Match the renamed field in the Avo app. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Address CodeRabbit review on PR #1707. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Document the OIDC-federation Role Assumption mode alongside the existing Access Keys mode: trust policy (Federated accounts.google.com + sts:AssumeRoleWithWebIdentity + aud condition), GCP-service-account audience the customer pastes, per-publish JWT exchange flow, security framing, config table rows, and OIDC-specific failure entries. Access Keys mode unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

thoragudf · 2026-06-01T16:11:53Z

@coderabbitai review

coderabbitai · 2026-06-01T16:11:58Z

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@pages/publishing/publishing/amazon-s3.mdx`:
- Around line 58-74: Update the OIDC trust policy JSON: keep "Principal": {
"Federated": "accounts.google.com" } intact, but change the Condition so
"accounts.google.com:aud" matches the Google ID token audience/client ID (not
the GCP service account email); if you need to restrict to a specific service
account, add a separate claim restriction using "accounts.google.com:sub" with
the service account's subject value rather than using the service account email
for "aud".

🪄 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: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 56584ce3-fd87-4c2d-8d8b-8cf72c0b2cba

📥 Commits

Reviewing files that changed from the base of the PR and between 359e2d0 and 1b07666.

⛔ Files ignored due to path filters (1)

public/images/publishing_amazon_s3.svg is excluded by !**/*.svg

📒 Files selected for processing (2)

maggie/worktree-s3-integration-docs/state.json
pages/publishing/publishing/amazon-s3.mdx

CodeRabbit flagged that accounts.google.com:aud (= SA email) is caller-set and not an identity proof. Keep the documented config for this release; track hardening to accounts.google.com:sub as an inline TODO. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Trust policy now pins on accounts.google.com:sub (the service account's 21-digit unique ID) instead of :aud. The aud claim is caller-set and not an identity proof; sub is bound to Avo's service account and can't be forged. - Update the pasted value (email -> service account ID), per-publish flow, security framing, and the AssumeRoleWithWebIdentity failure entry to match. - Replace the Authentication modes bullets with a comparison table and pull both setups under that header as ### Access Keys / ### Role Assumption (OIDC). - Move Configure above Authentication modes; its table now holds only the fields common to both modes, with auth-specific fields in a per-mode table. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The maggie/ state file was swept into earlier commits via git add -A. It's local PR-babysitter state, not documentation; untrack it and gitignore it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Document that Avo's OIDC token-minting service account holds no IAM roles in Avo's GCP project, so a compromise of the publish path can't pivot inside Avo. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

thoragudf · 2026-06-04T13:56:24Z

@coderabbitai review

coderabbitai · 2026-06-04T13:56:31Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Access Key authentication was removed from the integration (monorepo PR #9546); OIDC Role Assumption is now the only path. - Delete the "Authentication modes" comparison and the Access Keys subsection. - Rename the Role Assumption section to "Configuring AWS for Avo" — it's the setup. - Single field table (no mode prefixes); drop the per-mode framing/sentences. - Security: drop the access-keys paragraph; keep OIDC + zero-role-SA bullets. - Failure handling: drop the access-key error row and all "(… mode)" suffixes. - Org-policy callout now points to support instead of an Access Keys fallback. - Use the real service-account sub in the trust policy example. - Fold in two limitations: one integration = one bucket; fixed object-key layout. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

thoragudf · 2026-06-05T14:44:21Z

@coderabbitai review

coderabbitai · 2026-06-05T14:44:28Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

vercel Bot deployed to Preview May 29, 2026 11:42 View deployment

coderabbitai Bot requested changes May 29, 2026

View reviewed changes

Comment thread pages/publishing/publishing/amazon-s3.mdx

Use real Amazon S3 bucket icon for the logo

76897ef

Replace the grey placeholder with the S3 bucket glyph from the app (IconS3Integration.res), converted to a static SVG with a fixed gradient id. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview May 29, 2026 11:52 View deployment

Rename "Key Prefix" to "Folder Prefix"

3a0a87d

Match the renamed field in the Avo app. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview May 29, 2026 11:56 View deployment

Clarify Folder Prefix description

8a9067d

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview May 29, 2026 12:01 View deployment

Use canonical JSON Schema capitalization

41abdf4

Address CodeRabbit review on PR #1707. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview May 29, 2026 12:07 View deployment

coderabbitai Bot approved these changes May 29, 2026

View reviewed changes

vercel Bot deployed to Preview June 1, 2026 16:10 View deployment

coderabbitai Bot requested changes Jun 1, 2026

View reviewed changes

Comment thread pages/publishing/publishing/amazon-s3.mdx Outdated

coderabbitai Bot approved these changes Jun 1, 2026

View reviewed changes

vercel Bot deployed to Preview June 1, 2026 16:26 View deployment

thoragudf and others added 2 commits June 2, 2026 11:11

Stop tracking Maggie tooling state in docs repo

fff646d

The maggie/ state file was swept into earlier commits via git add -A. It's local PR-babysitter state, not documentation; untrack it and gitignore it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview June 2, 2026 11:12 View deployment

Add zero-role service account note to OIDC security

0713c06

Document that Avo's OIDC token-minting service account holds no IAM roles in Avo's GCP project, so a compromise of the publish path can't pivot inside Avo. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview June 4, 2026 13:56 View deployment

thoragudf requested a review from logason June 4, 2026 14:21

vercel Bot deployed to Preview June 5, 2026 14:45 View deployment

Conversation

thoragudf commented May 29, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

TODOs left for follow-up

Verification

Summary by CodeRabbit

Uh oh!

vercel Bot commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Suggested reviewers

Poem

Uh oh!

logason commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📝 Changed routes:

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

thoragudf commented Jun 1, 2026

Uh oh!

coderabbitai Bot commented Jun 1, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

thoragudf commented Jun 4, 2026

Uh oh!

coderabbitai Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thoragudf commented Jun 5, 2026

Uh oh!

coderabbitai Bot commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

thoragudf commented May 29, 2026 •

edited by coderabbitai Bot

Loading

vercel Bot commented May 29, 2026 •

edited

Loading

coderabbitai Bot commented May 29, 2026 •

edited

Loading

logason commented May 29, 2026 •

edited

Loading

coderabbitai Bot commented Jun 4, 2026 •

edited

Loading

coderabbitai Bot commented Jun 5, 2026 •

edited

Loading