DOC-2235: Document the Visual pipeline editor for Redpanda Connect - #651
Open
JakeSCahill wants to merge 9 commits into
Open
DOC-2235: Document the Visual pipeline editor for Redpanda Connect#651JakeSCahill wants to merge 9 commits into
JakeSCahill wants to merge 9 commits into
Conversation
Adds a new "Explore the Visual editor" section to the Connect quickstart and a July 2026 changelog entry, plus a Doc Detective test embedded inline in the quickstart that verifies the documented procedure against the real Cloud console and regenerates the canvas screenshot in the same run. Also fixes a sharp/@img platform-binary version mismatch in package-lock.json (would have broken the daily screenshot-test cron job on GitHub's real linux-x64 runners) and adds the GitHub Actions workflow that runs the test daily against preprod and prod. Co-Authored-By: Claude Sonnet 5 <[email protected]>
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughAdds Visual editor documentation for Redpanda Connect pipelines, including an embedded UI test and screenshot. Introduces Doc Detective scripts for inline testing, screenshot-size enforcement, cleanup, and screenshot standards linting. Adds package configuration, environment templates, and operational documentation. Adds GitHub Actions for scheduled/manual cloud screenshot tests and pull-request screenshot linting. Estimated code review effort: 3 (Moderate) | ~25 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
…path A future inline test on a new page would otherwise require remembering to add it to a manually maintained input array. Doc Detective already skips pages with no inline test comments cheaply, so scanning the whole tree costs nothing extra and needs no registration step per new test.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 10
🤖 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 @.github/workflows/doc-detective-screenshots.yml:
- Around line 57-66: Replace the hardcoded CLOUD_LOGIN_EMAIL values in the
preprod and production branches with environment-specific GitHub Actions
secrets, and write those secret values into tests/doc-detective/.env. Keep the
existing environment selection and password handling unchanged, using distinct
secrets for each test account.
- Around line 41-42: Apply least-privilege checkout settings in both workflow
files: add top-level permissions granting only contents read and configure each
actions/checkout@v4 step with persist-credentials disabled. Update
.github/workflows/doc-detective-screenshots.yml lines 41-42 and
.github/workflows/screenshot-standards-lint.yml lines 17-18; both sites require
the same change.
In `@modules/develop/pages/connect/connect-quickstart.adoc`:
- Line 387: Update the pipeline setup instruction near the Visual tab step to
explicitly direct users to create a new pipeline or open an existing one before
selecting the Visual tab. Align the documentation with the test flow that
navigates to the pipeline creation page, while preserving the existing
YAML/Visual tab guidance.
- Around line 434-443: Correct the screenshot fixture’s typed YAML keys by
changing the literal ppipeline: and ooutput: entries to pipeline: and output:.
Preserve the surrounding SHIFT and wait steps so the keys remain at the intended
top-level indentation and the input/processors/output structure is represented
correctly.
- Line 416: Update the Doc Detective step identified by the find configuration
for the “Save” element so it performs a click by enabling the click option,
matching the interaction behavior of the surrounding steps.
In `@tests/doc-detective/.env.example`:
- Around line 1-4: Update the comments in .env.example to state that login is
performed by embedded steps in the AsciiDoc tests, specifically
connect-quickstart.adoc, and remove references to login-inline.json,
config-level beforeAny, and run-inline.js.
In `@tests/doc-detective/lint-screenshots.js`:
- Around line 38-49: Update resolveImagePath to accept the current filePath and
resolve module-local image references such as image::filename.png[] against the
current module’s images directory, deriving the module from filePath. Preserve
existing remote-image handling and cross-module module:filename resolution, and
update its callers to pass filePath so existence and size checks run for local
references.
In `@tests/doc-detective/README.md`:
- Around line 95-101: Update the README description of lint-screenshots.js to
remove the claim that it validates screenshot naming, unless a corresponding
naming check is implemented. Keep the documented checks for alt text and
resolvable image existence/size accurate.
In `@tests/doc-detective/run-inline.js`:
- Around line 108-111: Redact resolved credentials and other sensitive step data
before serializing report in tests/doc-detective/run-inline.js lines 108-111,
then persist only the sanitized report. Update
.github/workflows/doc-detective-screenshots.yml lines 74-82 to upload that
sanitized report, or remove the report artifact upload entirely.
- Around line 115-116: The exit-code logic in run-inline.js must treat skipped
validation contexts as failures, not only explicit test failures. Update the
condition around report.summary.tests.fail so any requested inline test/context
with a non-PASS result, including SKIPPED, sets process.exitCode to 1 while
preserving the withinSizeLimit failure behavior.
🪄 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: CHILL
Plan: Pro Plus
Run ID: b5e369c3-c49c-46b8-9d5a-891ba9b99959
⛔ Files ignored due to path filters (2)
modules/shared/images/rpcn-visual-editor-canvas-v26-2.pngis excluded by!**/*.pngpackage-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (10)
.github/workflows/doc-detective-screenshots.yml.github/workflows/screenshot-standards-lint.yml.gitignoremodules/develop/pages/connect/connect-quickstart.adocmodules/get-started/pages/whats-new-cloud.adocpackage.jsontests/doc-detective/.env.exampletests/doc-detective/README.mdtests/doc-detective/lint-screenshots.jstests/doc-detective/run-inline.js
- Redact resolved credentials before persisting last-inline-report.json, and stop treating SKIPPED test contexts as an implicit pass — a broken CI environment that never launches a browser was previously reported as a successful run. - Add least-privilege permissions and persist-credentials: false to both workflows; move test-account emails to secrets alongside their passwords (PREPROD_EMAIL, EMAIL). - Fix the inline test: "Open a pipeline" -> "Open an existing pipeline, or create a new one" to match what the test itself does; add the missing click:true on the Save step so it actually verifies Save works instead of only locating the button. - lint-screenshots.js now resolves same-module image:: references (no "module:" prefix) instead of silently skipping them — surfaced 5 more pre-existing oversized images alongside the 9 already known, all out of scope for this PR. - Fix a stale .env.example comment left over from an earlier login-flow design, and a README claim that the linter checks image naming (it doesn't). Not applying the "ppipeline:"/"ooutput:" suggestion: those are an intentional, tested workaround for a real WebDriver/Monaco bug where the character typed immediately after a Shift+Home selection gets dropped, documented in tests/doc-detective/README.md's Gotchas section. Replying on the PR with that context.
Compresses the 13 pre-existing oversized PNGs (5 newly caught by the lint-screenshots.js module-local-image fix, 9 already known) down to the 100KB ceiling: resize to the standard's own spec (960px display width at 2x retina = 1920px file width, the actual root cause for most of these — several were captured well past that) plus palette PNG quantization where resizing alone wasn't enough. Verified visually, no discernible quality loss. Also fixes cloud-mcp.gif (2236KB, 143 frames) via gifsicle: reduced frame count, lossy compression, and resize, down to 80KB. Adds tests/doc-detective/fix-oversized-image.js so the next oversized PNG doesn't need this figured out from scratch, and documents the GIF approach (which needs visual judgment calls a script shouldn't make silently) in tests/doc-detective/README.md. Adds gifsicle as a devDependency for portable GIF tooling.
- Step 3's "*+*" (bold-wrapped bare plus sign) hit an AsciiDoc landmine: a "+" with no adjacent whitespace on either side is the delimiter for the +...+ passthrough macro. With two such spans on the same line, they paired up and swallowed everything between them, rendering as stray literal asterisks with the button description missing. Backslash-escaping was tried and found unreliable (Asciidoctor rendered the first occurrence clean but literally showed the backslash on the second). Fixed by rephrasing to "plus-sign icon" — also more correct per the style guide, since an icon with no visible label isn't "UI text" that bold is meant to indicate. - The screenshot crop bled into the tab bar (top) and a toolbar row (bottom) by a partial, cut-off sliver of each — not from the padding being too small, but too large: `.react-flow`'s own bounding box starts right at the canvas edge, so any padding at all pulls in whatever sits just outside it. Zeroed top/bottom padding, kept it on left/right where there was no bleed. - The example pipeline's "generate" input had no `mapping` field, i.e. no actual logic for what data to generate — the linter's cascading "expected object value, got !!null" / "field X is invalid" errors on generate were a real, confusing symptom of that real gap, not just cosmetic noise. Added one. (Tried the same investigation for the remaining `log` processor errors and a click-to-refresh workaround for the Problems-count display, but the latter proved flaky/ non-deterministic run to run — reverted rather than ship something that only sometimes reduces the count. The Problems/Unsaved chips showing a nonzero count is exactly the UI behavior this section of the docs describes, so it's left as whatever the real state is.)
Verified live against preprod: introducing a YAML syntax error does NOT make the Visual tab keep showing the last valid pipeline. It shows an explicit "Unable to visualize this pipeline — fix the YAML in the YAML tab" banner with skeleton placeholders instead. The "keeps showing last valid" behavior is real, but belongs to the YAML tab's own structure tree sidebar (a separate feature, confirmed showing "Showing the last valid outline — the current YAML is invalid"), not the Visual tab itself — the original text conflated the two. Also confirmed the other half of that paragraph is accurate: editing a node's config and closing its panel (not just clicking Save or selecting another node) does write the edit into the YAML immediately, verified by editing a field, closing without saving, and checking the YAML tab directly.
Previously the workflow only ran our own run-inline.js wrapper and uploaded artifacts for a human to check by hand — the official action's create_pr_on_change/create_issue_on_fail capability was documented as "future scope" but never wired up. Switches the CI workflow to run the tests via doc-detective/github-action directly: - create_pr_on_change: true — a screenshot diff beyond the accepted threshold now opens a PR automatically instead of silently updating a build artifact nobody looks at. - create_issue_on_fail: true — a genuine step failure (not a screenshot diff) files an issue instead. Deliberately does NOT use the action's default issue_body, which embeds the raw $RESULTS object — that contains the resolved CLOUD_LOGIN_PASSWORD substituted into this test's login steps, posted via a direct API call that bypasses GitHub's log secret-masking. Overridden to link the (correctly masked) run logs instead. - Documents the action's built-in `integrations` input (including `claude`) as the ready-to-enable hook for the "point an LLM at the filed issue" future work — already built into the action we're now using, just not turned on until a claude-mentions-responding integration exists for this repo. Extracted the test config from an inline object in run-inline.js into tests/doc-detective/config.json so local runs and the action's own `config` input use identical settings instead of two copies that can drift apart. Known gap, called out in both the workflow comments and the README: the action installs its own copy of doc-detective rather than using this repo's node_modules, so it doesn't inherit the sharp/@img version-pinning fix in package.json's overrides. Needs a manual workflow_dispatch run to confirm it doesn't hit that same upstream conflict before trusting the daily cron on it.
The previous guidance assumed act defaults to a safe fake GITHUB_TOKEN. It doesn't: with no token explicitly provided, act silently pulls a real, authenticated one from the local gh CLI session. A local test run of the new doc-detective/github-action integration hit this and filed a real issue (#652, closed once caught) against this repo from what was supposed to be a local dry run. Verified the fix (-s GITHUB_TOKEN=<garbage>) actually prevents any real API mutation, but it's blunt: act uses the same token to `git clone` the marketplace action itself, so a bad token breaks that too, before ever reaching create_pr_on_change/create_issue_on_fail. There's no way to give act a token valid enough to fetch a public action but denied write access to this repo specifically. Net effect documented plainly: this workflow's PR/issue-creation behavior can't be safely dry-run locally at all. act is only useful here to sanity-check job structure/secrets wiring (expect it to fail at the action-clone step with the safe token). Login/browser/screenshot behavior should be validated via run-inline.js directly instead, and the actual create_pr_on_change/create_issue_on_fail behavior needs a real workflow_dispatch run once this workflow is reachable on GitHub.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Jira: https://redpandadata.atlassian.net/browse/DOC-2235
Summary
connect-quickstart.adocand a July 2026 changelog entry inwhats-new-cloud.adoctests/doc-detective/README.mdfor how this works).github/workflows/doc-detective-screenshots.yml(daily cron + manual dispatch against preprod/prod/both) and a fast PR-time screenshot-standards lint workflowsharp/@imgplatform-binary version mismatch inpackage-lock.jsonthat would have broken the daily screenshot-test cron job the first time it ran on GitHub's real linux-x64 runners (filed upstream: appium/appium#22554)Test plan
require("sharp")smoke test passes with the corrected lockfileact(seetests/doc-detective/README.md)🤖 Generated with Claude Code