Repository navigation
docs: make secrets documentation factory-first - #937
rachaelrenk wants to merge 4 commits into
Conversation
Add factory secrets workflows and link legacy users to the current factory docs while preserving supported Oz CLI instructions. Co-Authored-By: Warp <agent@warp.dev>
Preserve upstream agent-doc restructuring and update its configuration page to link to factory secrets. Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR adds a factory-first secrets page, preserves the legacy cloud-agent secrets page as a compatibility reference, and updates factory cross-links and sidebar placement.
Concerns
- No blocking correctness, security, link/structure, comment-quality, test-quality, or spec-alignment concerns found in the attached diff.
- Pre-verdict audit: no code or documentation comments and no tests were added or changed;
spec_context.mdreports no approved spec context.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Address review feedback on setup, credential access, ECR configuration, and lifecycle procedures. Normalize closing link lists across affected pages. Co-Authored-By: Warp <agent@warp.dev>
Address review feedback on prerequisites, field labels, access grants, and navigation wording. Remove the redundant factory pointer from the legacy page description. Co-Authored-By: Warp <agent@warp.dev>
hongyi-chen
left a comment
There was a problem hiding this comment.
approving to unblock, left some other suggestions!
| @@ -0,0 +1,208 @@ | |||
| --- | |||
| title: Managing secrets for factory agents | |||
There was a problem hiding this comment.
Maybe "Managing factory secrets"?
| ], | ||
| }, | ||
| { slug: 'factories/factory-skills', label: 'Factory skills' }, | ||
| { slug: 'factories/secrets', label: 'Secrets' }, |
There was a problem hiding this comment.
I think “Secrets” works as the title, but wonder if it makes more sense to move this under Infrastructure, alongside the other security-related docs? Since secrets are team-level resources rather than specific to an individual factory, the current placement feels a bit out of place.
Factory Configuration
- Factory agents
- Factory skills
- Factory automations
- Definitions as code
- Infrastructure
- About infrastructure and security
- Deployment patterns
- Warp-hosted execution
- Runners
- Managed self-hosting
- Secrets
|
|
||
| For a Warp-managed factory, edit the agent in the web app. Externally managed factories have read-only configuration here. Use [definition files](#using-definition-files) instead. | ||
|
|
||
| 1. In the {VARS.FACTORY_WEB_APP}, click your factory in the sidebar to expand it, then click **Agents**. |
There was a problem hiding this comment.
might be worth linking to platform.warp.dev perhaps?
|
|
||
| The first check confirms injection. The second verifies authentication for that operation. | ||
|
|
||
| ## AWS ECR credentials |
There was a problem hiding this comment.
i wonder if we should turn this ECR stuff into another page that lives under the secrets page
|
|
||
| <span id="warp-assumed-the-role-but-could-not-get-an-ecr-token" /> | ||
|
|
||
| ### ECR token retrieval fails |
There was a problem hiding this comment.
similar comment to above comment re: ECR
What this feature does
Managed secrets give factory agents credentials for external services without putting values in prompts or definition files. Teams create credentials in the Warp Factories web app and grant agents access separately. This PR documents existing functionality, not a new product release.
Summary
Make secrets documentation factory-first while preserving supported legacy workflows. Customers searching for secrets currently land on the Oz-oriented page and mistake it for the factory workflow.
Requested in the Slack discussion.
Changes
/factories/secrets/with current web-app creation, agent assignment, definition inheritance, rotation, deletion, limits, and ECR guidance./platform/secrets/, label it as legacy, and put a prominent factory callout before its instructions. Preserve supported CLI examples, standalone scoping guidance, and compatibility anchors.Content design plan
Audience and JTBD: An engineer configuring a factory agent to authenticate to an external API, who found the secrets docs through search and needs the current setup workflow. Secondary audience: an existing user maintaining secrets through legacy Oz entry points.
Problem: Search and factory cross-links send both audiences to a mixed page that foregrounds the old surface and blurs which credentials a factory agent receives. This is grounded in the customer confusion reported in the Slack thread.
Goals:
Purpose and value: Establish one factory-facing home for the complete task while retaining a clearly labeled compatibility reference. Reorganize existing documented capabilities rather than add an unrelated feature page.
Content type: Feature documentation (combined), with a short explanation of ownership and access followed by setup and management procedures.
Skill and template:
draft_docsanddraft_feature_doc, using.agents/templates/feature-doc.md.High-impact scenarios: Covers team credentials, individual-agent and factory-definition grants, rotation, removal, and ECR image-pull setup. Preserves personal-secret and legacy CLI guidance. Excludes a general legacy-docs migration, new credential integrations, and duplicated harness/inference authentication guides.
Availability: Human-requested reorganization of existing public functionality. Current secrets screens were checked against the deployed public app bundle on 2026-10-20, separately from the source snapshots below.
Validation
After merging current
origin/main:npm run typecheckpassed.npm run test:heading-varspassed.npm run buildpassed.npm run test:heading-tocspassed.npm run test:homepage-json-ldpassed.Factorycapitalization warnings in unchanged lines.git diff --checkpassed.Trunk is not installed locally. No real secrets were created, retrieved, printed, rotated, or deleted; authenticated end-to-end credential operations and ECR pulls were not exercised.
Source verification
Source snapshots are Git tree IDs, not claims that these exact revisions are deployed:
warp-servertree744b4c1fb94c0d380aaf3b2c961cefe45f8c7d36:client/packages/factory/src/pages/Secrets/{CreateSecretPage,FactorySecretPicker,SecretDetailPage}.tsx,pages/FactoryAgents/{AgentConfigForm,FactoryAgentEditor}.tsx,logic/factoryfile/{resolution/resolution.go,projector/agent.go}, andlogic/managed_secrets/inject.go.warp-internaltreede1165cb82105e79c270ed3db7a7a9c3dc513f77:crates/warp_cli/src/secret.rsandcrates/managed_secrets/src/secret_value.rs.factory-Bq3MHiYLCLDPtSiT.js: confirmed the full-page secrets creation/detail routes and current creation controls. This was a bundle inspection, not an authenticated browser walkthrough.Unverified claims
None outstanding for the newly documented UI labels, CLI flags, and secret-list inheritance behavior: these were checked against source and, for the current secrets surface, the public bundle. Functional credential operations remain an explicit testing limitation above.
Documentation risk
Risk: engineering-review-required
Rationale: Adds a factory workflow page and revises credential-access, configuration, UI, and security guidance.
Source files consulted: warp-server/logic/managed_secrets/inject.go, warp-server/logic/factoryfile/resolution/resolution.go, warp-internal/crates/warp_cli/src/secret.rs; exact snapshots recorded under Source verification
Requested engineering reviewers: none; source-owner resolution returned no matches
Engineering review status: pending
Docs override: none
Agent context
Agent conversation
Co-Authored-By: Warp agent@warp.dev