Skip to content

[5650] chore(ci): make clone mode the only Railway preview path (WP4) - #5678

Merged
mmabrouk merged 9 commits into
mainfrom
wp4-clone-cutover
Aug 3, 2026
Merged

[5650] chore(ci): make clone mode the only Railway preview path (WP4)#5678
mmabrouk merged 9 commits into
mainfrom
wp4-clone-cutover

Conversation

@mmabrouk

@mmabrouk mmabrouk commented Aug 3, 2026

Copy link
Copy Markdown
Member

Final step of the clone-based Railway preview redesign (#5650, WP4). Merge when the clone-mode soak looks good; rollback before merge is flipping RAILWAY_PREVIEW_MODE back to legacy, and rollback after merge is reverting this PR.

Clone mode is already live via the repo variable. This PR removes the legacy preview path so clone is the only one, and finishes the cutover items the earlier PRs marked TODO(cutover).

What changes

  • Workflows 14/41/43/45 become clone-only. The mode job, the mode inputs, the Railway CLI installs, and every legacy setup/deploy/destroy step are gone. The stale-clone sweep and its daily cron remain. Job outputs that the tests job and the PR comment consume now come from the clone/verify steps directly.
  • Template location is config-driven. The workflows read vars.RAILWAY_TEMPLATE_PROJECT and vars.RAILWAY_TEMPLATE_ENV (defaults: the current template project), so moving the template later is a variable change plus one project line in template.json, no code edits.
  • Template pins current images. template.json moves to v0.108.0 app images and per-service content-addressed wrapper tags (the images workflow 42 publishes); apply.sh resolves per-service wrapper tags from the definition. The live template already matches this definition (apply.sh --dry-run is CLEAN), so the daily drift check goes green with this merge.
  • Four legacy preview scripts are deleted (preview-create-or-update.sh, preview-resolve-env.sh, preview-destroy.sh, preview-cleanup-stale.sh), each with a repo-wide grep proving zero remaining references.
  • Docs match reality. The main README describes clone previews as the path (with the two config variables and the rollback story) and moves the standalone scripts under a self-hosting heading. The template README documents how to regenerate wrapper content tags when the wrapper sources change.

What deliberately stays

bootstrap.sh, configure.sh, deploy-from-images.sh, upgrade.sh, smoke.sh, and the wrapper image sources stay untouched: they serve self-hosters deploying Agenta on their own Railway, the template-maintenance path, and workflow 42's byte-faithfulness guard reads deploy-from-images.sh directly.

Verification

  • bash -n and shellcheck clean on all touched scripts; actionlint clean on all four workflows; template.json parses and substitutes with zero leftover placeholders.
  • Live template converged and verified CLEAN against this PR's exact definition (v0.108.0 apps + content-tagged wrappers).
  • This PR's own preview runs in clone mode and is part of the soak evidence.

Closes #5650

https://claude.ai/code/session_011zdniFW44QDqcs4Nz8n3hr

@dosubot dosubot Bot added the size:XL This PR changes 500-999 lines, ignoring generated files. label Aug 3, 2026
@vercel

vercel Bot commented Aug 3, 2026

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
agenta-documentation Ready Ready Preview Aug 3, 2026 3:38pm

Request Review

@coderabbitai

coderabbitai Bot commented Aug 3, 2026

Copy link
Copy Markdown

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Summary by CodeRabbit

  • New Features

    • Preview environments now use a streamlined clone-based deployment and cleanup flow.
    • Preview deployments require pinned image tags for predictable releases.
    • Gateway, Redis, and SeaweedFS wrapper images can be configured independently.
    • Updated templates include application version 0.108.0 and improved service health checks.
    • Clone environments can automatically receive the configured authentication key.
  • Documentation

    • Added guidance for CI previews, standalone self-hosting, configurable templates, image tags, lifecycle behavior, and acceptance evidence.
    • Added a historical handoff covering the preview clone rollout.

Walkthrough

This change completes the Railway preview cutover to clone-only environments. Workflows require pinned image tags, use configurable template locations, verify cloned environments, and clean up cloned environments. The template supports separate wrapper-image tags, and documentation records the new lifecycle.

Changes

Railway preview cutover

Layer / File(s) Summary
Template image-tag contract
hosting/railway/oss/template/template.json, hosting/railway/oss/template/apply.sh, hosting/railway/oss/template/README.md
The template replaces wrapper_tag with separate pinned gateway, Redis, and SeaweedFS tags. apply.sh validates and substitutes each tag while retaining a shared override.
Clone-only preview workflows
.github/workflows/14-check-pr-preview.yml, .github/workflows/41-railway-setup.yml, .github/workflows/43-railway-deploy.yml, .github/workflows/45-railway-cleanup.yml, hosting/railway/oss/scripts/preview-clone-create.sh, hosting/railway/oss/scripts/preview-clone-destroy.sh
Setup, verification, and cleanup use the configured template environment without legacy mode branches or Railway CLI installation. Clone setup applies the acceptance-test auth key.
Preview documentation and handoff
docs/design/railway-preview-clone-spike/HANDOFF.md, hosting/railway/oss/README.md, hosting/railway/oss/template/README.md, hosting/railway/oss/scripts/preview-clone-destroy.sh
Documentation describes the clone-only lifecycle, configuration, wrapper images, operational evidence, and WP4 cutover state.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant PRWorkflow
  participant RailwaySetup
  participant CloneScript
  participant RailwayDeploy
  participant RailwayCleanup
  PRWorkflow->>RailwaySetup: pass build outputs and pinned image tag
  RailwaySetup->>CloneScript: create preview clone and apply CI auth key
  CloneScript->>RailwayDeploy: provide cloned environment
  RailwayDeploy->>PRWorkflow: return preview URL and verification logs
  PRWorkflow->>RailwayCleanup: request cleanup
  RailwayCleanup->>CloneScript: destroy clone and sweep stale environments
Loading

Possibly related PRs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 40.00% which is insufficient. The required threshold is 60.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly identifies the primary change: making clone mode the only Railway preview path.
Description check ✅ Passed The description directly explains the clone-only cutover, legacy path removal, template updates, documentation changes, and verification.
Linked Issues check ✅ Passed The changes implement issue #5650 by completing the clone-based preview cutover, template versioning, workflow migration, cleanup, and drift-related documentation.
Out of Scope Changes check ✅ Passed The workflow, script, template, documentation, and handoff changes support the linked issue objectives without identified unrelated code changes.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch wp4-clone-cutover

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.

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Railway Preview Environment

Status Destroyed (PR closed)

Updated at 2026-08-03T16:06:37.114Z

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 2


ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3b4f322c-925c-4e30-972a-dff9dd858557

📥 Commits

Reviewing files that changed from the base of the PR and between 431b6a7 and 1c2a56d.

📒 Files selected for processing (15)
  • .github/workflows/14-check-pr-preview.yml
  • .github/workflows/41-railway-setup.yml
  • .github/workflows/43-railway-deploy.yml
  • .github/workflows/45-railway-cleanup.yml
  • docs/design/railway-preview-clone-spike/HANDOFF.md
  • hosting/railway/oss/README.md
  • hosting/railway/oss/scripts/preview-cleanup-stale.sh
  • hosting/railway/oss/scripts/preview-clone-create.sh
  • hosting/railway/oss/scripts/preview-clone-destroy.sh
  • hosting/railway/oss/scripts/preview-create-or-update.sh
  • hosting/railway/oss/scripts/preview-destroy.sh
  • hosting/railway/oss/scripts/preview-resolve-env.sh
  • hosting/railway/oss/template/README.md
  • hosting/railway/oss/template/apply.sh
  • hosting/railway/oss/template/template.json
💤 Files with no reviewable changes (4)
  • hosting/railway/oss/scripts/preview-destroy.sh
  • hosting/railway/oss/scripts/preview-create-or-update.sh
  • hosting/railway/oss/scripts/preview-cleanup-stale.sh
  • hosting/railway/oss/scripts/preview-resolve-env.sh

Comment thread docs/design/railway-preview-clone-spike/HANDOFF.md Outdated
Comment thread docs/design/railway-preview-clone-spike/HANDOFF.md Outdated
@mmabrouk

mmabrouk commented Aug 3, 2026

Copy link
Copy Markdown
Member Author

First soak finding, fixed in-place: the first clone-mode preview ran green through clone/deploy/smoke, but the acceptance suites failed with 401s — legacy previews wrote the CI test auth key into every environment at configure time, while clones inherit the template's own generated key. Fix (commit c827192): workflow 41 passes secrets.AGENTA_TEST_OSS_AUTH_KEY to the clone step, and preview-clone-create.sh upserts it onto the api and services services before anything deploys. Without the variable (local runs), clones keep the template's self-contained key. This push's preview run validates the fix.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: dd54eef3-1602-465b-a4f1-27e6d6bf8c74

📥 Commits

Reviewing files that changed from the base of the PR and between 1c2a56d and c827192.

📒 Files selected for processing (2)
  • .github/workflows/41-railway-setup.yml
  • hosting/railway/oss/scripts/preview-clone-create.sh
🚧 Files skipped from review as they are similar to previous changes (1)
  • hosting/railway/oss/scripts/preview-clone-create.sh

Comment thread .github/workflows/41-railway-setup.yml
@mmabrouk

mmabrouk commented Aug 3, 2026

Copy link
Copy Markdown
Member Author

Second and third soak findings, both fixed. The first clone-mode previews surfaced two gaps where the template did not carry configuration that legacy configure.sh used to apply at deploy time:

  1. CI auth key (fixed, verified). Legacy wrote AGENTA_AUTH_KEY into seven services; clones inherited the template's own generated key, so admin calls returned 401. preview-clone-create.sh now upserts the CI key onto all seven (web, api, services, worker-queues, worker-streams, cron, alembic) before anything deploys. The API acceptance suite went from 10 failures to green.
  2. Service healthchecks (fixed here). Legacy set healthcheckPath on gateway (/), api, services, and runner (/health); the template had none, so Railway routed traffic to containers before they were ready and UI tests hit 60s waitForResponse timeouts. The definition now declares them, and the live template is converged and CLEAN.

Both were pre-existing gaps between the template and legacy behavior, not defects in the clone mechanism itself: cloning, patching, deploying, smoke-testing, and teardown have worked in every run. This is exactly what the soak was for.

@mmabrouk

mmabrouk commented Aug 3, 2026

Copy link
Copy Markdown
Member Author

Five flaky web acceptance tests disabled at Mahmoud's direction, tracked in #5695 with the evidence and the re-enable criteria: app deletion, chat-prompt app creation, human-annotation mismatched testset, and two playground run-variant tests. Each is skipped at the declaration with a one-line reason pointing at the issue. They failed the same way under the old preview system, so this is not a regression from the cutover. Also in this push: the runner healthcheck is removed from the template, since the runner listens on 8765 with no PORT variable and Railway cannot probe it (the legacy CLI call that set it never persisted, so it never worked there either); gateway, api, and services keep theirs.

@mmabrouk

mmabrouk commented Aug 3, 2026

Copy link
Copy Markdown
Member Author

CodeRabbit findings addressed (commit a0199ce):

  • Major, real bug, fixed: 41-railway-setup.yml referenced AGENTA_TEST_OSS_AUTH_KEY without declaring it under on.workflow_call.secrets, so GitHub would have passed an empty value and the clone would have silently kept the template's own key. Declared it with required: false (the script already no-ops without it, which is the correct local-run behavior). actionlint is now clean on that file; it had been flagging this.
  • Minor, docs: expanded the handoff's commit-discipline note into the explicit five-step verification (including the lane-scope diff and the local-versus-remote SHA check, since but push prints nothing on success and can silently no-op), and removed the line that began with a bare #5668 so Markdownlint stops reading it as a heading.

Worth flagging that the first one mattered: the auth-key fix earlier in this PR is what took the API suite from ten failures to green, and this missing declaration would have quietly undone it on any future run.

@mmabrouk
mmabrouk enabled auto-merge August 3, 2026 15:56
@dosubot dosubot Bot added the lgtm This PR has been approved by a maintainer label Aug 3, 2026
@mmabrouk
mmabrouk merged commit 69e2165 into main Aug 3, 2026
67 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci/cd lgtm This PR has been approved by a maintainer size:XL This PR changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

(chore) Railway previews: clone a template environment per PR instead of creating 13 services imperatively

2 participants