docs(self-host): document AGENTA_SERVICES_INTERNAL_KEY by mmabrouk · Pull Request #6276 · Agenta-AI/agenta

mmabrouk · 2026-08-25T15:16:57Z

Summary

v0.114.0 (71a2857) added AGENTA_SERVICES_INTERNAL_KEY as a required secret: the API's startup lifespan() now calls validate_platform_runtime_key() unconditionally and raises if the key is unset or the replace-me placeholder, so the API refuses to start without it.
The example env files (env.oss.gh.example, env.oss.dev.example, env.ee.gh.example, env.ee.dev.example), the Helm chart (secrets.yaml, values.schema.json, values.oss.example.yaml), and hosting/railway/oss/README.md already document it — but the public self-host docs and the EE Docker Compose README did not, so a self-hoster following only the docs would hit an undocumented startup crash on upgrade.
Adds the key everywhere AGENTA_AUTH_KEY/AGENTA_CRYPT_KEY are already documented as required secrets: the configuration reference, the Docker Compose remote-deploy guide, the Kubernetes deploy guide (values snippet, secrets table, troubleshooting section), the Railway deploy guide, and the EE Docker Compose README.

Test plan

Docs-only change; verified against the v0.114.0 source (71a2857a2a) that this key has no AGENTA_AUTH_KEY fallback and that the API's startup validation is unconditional.
Docs build (docusaurus build) if CI runs it on this PR.

https://claude.ai/code/session_01LDH8EkbpV3sQDj2kAww5Lh

v0.114.0 (71a2857) added AGENTA_SERVICES_INTERNAL_KEY as a required secret: the API's startup lifespan now calls validate_platform_runtime_key() unconditionally and raises if it is unset or the "replace-me" placeholder, so the API refuses to start without it. The example env files, the Helm chart, and the Railway automation scripts were already updated for this, but the public self-host docs and the EE compose README were not, so a self-hoster following only the docs would hit an undocumented startup crash. Adds the key alongside AGENTA_AUTH_KEY/AGENTA_CRYPT_KEY wherever those are documented as required secrets: the configuration reference, the Docker Compose remote-deploy guide, the Kubernetes deploy guide (values, secrets table, and troubleshooting), the Railway deploy guide, and the EE Docker Compose README.

vercel · 2026-08-25T15:17:03Z

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

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Error		Aug 25, 2026 3:31pm

CLAassistant · 2026-08-25T15:17:06Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

Agenta Team seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

coderabbitai · 2026-08-25T15:18:20Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 34121363-5f12-426f-9b79-842d780bb52b

📥 Commits

Reviewing files that changed from the base of the PR and between c03961d and 6b60f9f.

📒 Files selected for processing (2)

docs/docs/self-host/deploy/01-deploy-remotely.mdx
docs/docs/self-host/deploy/03-deploy-to-kubernetes.mdx

Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.

📝 Walkthrough

Summary by CodeRabbit

Documentation
- Documented the required AGENTA_SERVICES_INTERNAL_KEY configuration for self-hosted deployments.
- Added setup guidance for Docker Compose, Kubernetes, Railway, and remote deployments.
- Clarified shared API and Services configuration, secret generation, startup validation, and troubleshooting.
- Noted that the setting has no fallback and is not propagated to runners or sandboxes.

Walkthrough

The documentation now requires AGENTA_SERVICES_INTERNAL_KEY for self-hosted deployments. It describes key generation, shared values across API and Services containers, startup validation, the absence of an AGENTA_AUTH_KEY fallback, and deployment-specific configuration.

Changes

Services Internal Key

Layer / File(s)	Summary
Configuration contract `docs/docs/self-host/reference/01-configuration.mdx`	The configuration reference defines `AGENTA_SERVICES_INTERNAL_KEY` as a required shared secret. It documents generation, startup validation, fallback behavior, and environment exclusions.
Deployment guidance `docs/docs/self-host/deploy/01-deploy-remotely.mdx`, `docs/docs/self-host/deploy/03-deploy-to-kubernetes.mdx`, `docs/docs/self-host/deploy/04-deploy-on-railway.mdx`, `hosting/docker-compose/ee/README.md`	Deployment guides document key generation, required configuration, shared container values, security details, and Kubernetes troubleshooting.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 6b60f

This change documents a required self-hosting secret across the relevant deployment guides; no actionable merge-blocking risk remains beyond normal documentation checks.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains that the pull request documents the required AGENTA_SERVICES_INTERNAL_KEY across self-hosted deployment guides and the EE Docker Compose README.
Title check	✅ Passed	The title clearly and concisely identifies the documentation update for AGENTA_SERVICES_INTERNAL_KEY in self-hosted deployments.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
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.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (2 skipped: 2 unsupported.)

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/document-services-internal-key

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.}

coderabbitai

Actionable comments posted: 2

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 8c4dc698-c43f-4874-8ab2-c7cf8eb5b67a

📥 Commits

Reviewing files that changed from the base of the PR and between a09a0f0 and c03961d.

📒 Files selected for processing (5)

docs/docs/self-host/deploy/01-deploy-remotely.mdx
docs/docs/self-host/deploy/03-deploy-to-kubernetes.mdx
docs/docs/self-host/deploy/04-deploy-on-railway.mdx
docs/docs/self-host/reference/01-configuration.mdx
hosting/docker-compose/ee/README.md

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

- deploy-remotely.mdx: "the two Agenta keys" -> "the three Agenta keys" now that AGENTA_SERVICES_INTERNAL_KEY is listed alongside AUTH_KEY/CRYPT_KEY. - deploy-to-kubernetes.mdx: the existing-Secret requirements list was still AGENTA_AUTH_KEY/AGENTA_CRYPT_KEY/POSTGRES_PASSWORD only. A user following that instruction would omit AGENTA_SERVICES_INTERNAL_KEY from their pre-created Secret and hit the API's startup validation failure.

dosubot Bot added size:M This PR changes 30-99 lines, ignoring generated files. documentation Improvements or additions to documentation labels Aug 25, 2026

coderabbitai Bot reviewed Aug 25, 2026

View reviewed changes

Comment thread docs/docs/self-host/deploy/01-deploy-remotely.mdx

Comment thread docs/docs/self-host/deploy/03-deploy-to-kubernetes.mdx

vercel Bot had a problem deploying to Preview August 25, 2026 15:31 Failure

Navigation Menu

Uh oh!

docs(self-host): document AGENTA_SERVICES_INTERNAL_KEY - #6276

docs(self-host): document AGENTA_SERVICES_INTERNAL_KEY#6276
mmabrouk wants to merge 2 commits into
mainfrom
docs/document-services-internal-key

mmabrouk commented Aug 25, 2026

Uh oh!

vercel Bot commented Aug 25, 2026 •

edited

Loading

Uh oh!

CLAassistant commented Aug 25, 2026

Uh oh!

coderabbitai Bot commented Aug 25, 2026 •

edited

Loading

Summary by CodeRabbit

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

mmabrouk commented Aug 25, 2026

Summary

Test plan

Uh oh!

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

Uh oh!

Uh oh!

CLAassistant commented Aug 25, 2026

Uh oh!

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

Uh oh!

Summary by CodeRabbit

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel Bot commented Aug 25, 2026 •

edited

Loading

coderabbitai Bot commented Aug 25, 2026 •

edited

Loading