docs(factories): apply GitHub page review follow-ups from #526 - #562
Merged
hongyi-chen merged 6 commits intoAug 18, 2026
Merged
Conversation
…the GitHub page The Foreman name alignment pass in #560 updated control-room.mdx and quickstart.mdx to link the control room's **Foreman name** field to the definition's `alias` key, but it skipped the GitHub integration page because that page was still in the open PR for #526. The page uses `factory:<alias>` three times without ever saying where <alias> comes from, so a reader who only knows the control room label has no way to work out what their label is actually called. Bridge it on first use, matching the link convention the sibling pages now use. Co-Authored-By: Warp <agent@warp.dev>
Contributor
|
Your Warp account is not a member of any team with access to this repository. |
|
Your GitHub account is not connected to Warp. Connect it here. |
Contributor
|
Your GitHub account is not connected to Warp. Connect it here. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Collaborator
Author
|
This PR was generated with Warp. Comment   |
Contributor
|
Your Warp account is not a member of any team with access to this repository. |
|
Your GitHub account is not connected to Warp. Connect it here. |
hongyi-chen
marked this pull request as ready for review
August 18, 2026 01:06
Contributor
|
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 |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
This PR clarifies the first factory:<alias> reference on the GitHub integration page by linking <alias> to the factory Foreman name field. The change is limited to one documentation sentence and aligns the page with the terminology bridge described in the PR context.
Concerns
No blocking or inline concerns found. No approved spec context was available, and the security pass found no issues in this documentation-only change.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
…ctories-github-foreman-name-bridge
Two review comments on #526, which merged before they could be applied. Handle: the page said the shared account is @oz-agent. Maggie confirmed it will be @warp-factory. That matches warp-server's factoryGitHubHandleDefault, where FactoryGitHubHandle() is "permanently distinct from GitHubAgentHandle(): callers pick whichever applies, never fall back between them", and githubSeedAutomations materializes it into the seeded mention and assignment filters. Automations: the connect procedure ran to seven steps, of which the last five built an automation by hand. Default GitHub automations are seeded at factory creation, so that work isn't required to connect GitHub, and presenting it as part of setup implied the factory does nothing until you configure a trigger. Connecting is now the two steps it actually takes, followed by what the defaults already do and how to verify, with the custom-automation walkthrough moved to its own section for the cases the defaults don't cover. Sequencing: warp-server#15306 carries the handle rename and is still an open draft, so this page leads the server until it lands. Co-Authored-By: Warp <agent@warp.dev>
hongyi-chen
changed the title
…ctories-github-foreman-name-bridge # Conflicts: # src/content/docs/factories/integrations/github.mdx
hongyi-chen
added a commit
that referenced
this pull request
Aug 18, 2026
* docs(factories): lead the GitHub page with what the reader does Follow-up to #562. The page explained how mention routing is built before it said what to do with it, which put the reader through the architecture to answer "how do I hand this issue to my factory?" - "Mention the factory" opened on an internal fact ("a factory doesn't get its own GitHub handle") and asked the reader to expand `factory:<alias>` themselves, with `<alias>` defined mid-sentence via a link into the definition-syntax reference. It now leads with the two actions and a worked example (`factory:payments`), and explains the shared account only where it changes behavior: the label is what picks which factory answers. The Foreman name now links to Settings, where you read it, rather than to the YAML key. - The default automations were one dense paragraph; they are two bullets. - Dropped mechanism the reader can't act on: "both passes are best-effort", "CI payloads don't carry issue or label data", and "managed GitHub factories". - Replaced remaining internal vocabulary: "Warp-owned check" and "the registered factory directory". - GitLab carried the same `factory:<alias>` placeholder; same fix. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): clarity sweep over the launch pages Net -80 lines across the section, almost all of it interface narration and mechanism a reader can't act on. The pages were written as separate PRs, so each was reasonable alone and repetitive together. UI narration replaced with the task: - Slack's five-step connect was two actions (install the app, invite it to channels); two of the steps were the wizard describing itself. - GitLab's eight-step connect mixed factory creation, project selection, and hand-building an automation. - Linear had two near-identical connect procedures ending in "Both paths end in the same state." - Jira's step 3 was ~90 words and four actions. - Slack and Jira each walked through screens Warp doesn't own (Slack's app-removal flow, Atlassian's install flow); both now link out, so they can't drift silently. - The generic four-step "add an automation" walkthrough appeared on four integration pages. automation-filters owns it now; each integration page keeps only its own events and filters. Mechanism removed: Slack's managed-apps model and manager authorization, GitLab's manager service account, credential minting, one-year provisioning token and generated-ID naming, the per-run short-lived token, compute resolution precedence, and "this declares the `jira` integration for the factory." Said once instead of five to nine times: "filters route work, they don't restrict access" (now owned by automation-filters) and "the factory hands off at the pull request" (owned by how-factories-work). Also: - /platform/harnesses/ never mentioned that third-party harnesses need a Build plan, so a Free-plan reader found out at the error. Verified in warp-server/logic/agent_entitlements.go:114. - Dropped the `topic: factories` frontmatter key from ten pages. Every factories page is listed in sidebar.ts, so the key does nothing there and implied it was required. Co-Authored-By: Warp <agent@warp.dev> * Apply suggestion from @oz-for-oss[bot] Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com> --------- Co-authored-by: Warp Agent <agent@warp.dev> Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>
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.
Follow-ups to the GitHub integration page that couldn't land in #526, which merged first.
1. Maggie's review on #526
Both comments arrived after #526 merged, so they're applied here.
The handle should be
@warp-factory. Changed in both spots. This matches warp-server'sfactoryGitHubHandleDefault, whereFactoryGitHubHandle()is documented as "permanently distinct fromGitHubAgentHandle(): callers pick whichever applies, never fall back between them", andgithubSeedAutomationsmaterializes it into the seeded mention and assignment filters.factory_github_handleflag. Until it lands, this page names a handle that won't answer in production. That's fine while #508 is unmerged and the factories docs aren't public, but #15306 needs to land before #508 reachesmain. Worth someone owning that ordering.Default automations are populated on factory creation, so steps 3–7 weren't required. Correct, and the old shape actively misled: a seven-step procedure where five steps build an automation by hand implied the factory sits idle until you configure a trigger, when it's already listening. Connecting is now the two steps it actually takes, followed by what the defaults do and how to verify. The custom-automation walkthrough moved to its own Add a custom automation section, which is Maggie's suggested alternative and keeps it available for the cases the defaults don't cover — a failed CI run, a review request.
2. The original Foreman name bridge
#560's alignment pass linked the control room's Foreman name field to the definition's
aliaskey oncontrol-room.mdxandquickstart.mdx, but skipped this page because it was still unmerged in #526. The page usedfactory:<alias>three times without saying where<alias>comes from, so a reader who only knows the control room label had nothing connecting the two. Bridged on first use, matching the sibling pages' link convention.Verification
npm run buildexits 0, with only the pre-existing/404route-priority warningconnect-github-to-a-factory,add-a-custom-automation, andmention-the-factoryall emit anchor IDs, and thatfactory-as-code/index.htmlemitsid="alias"so the bridge link resolves@warp-factoryoccurrences render, 0oz-agentremain on the pagestyle_lint --changedreports 0 errors; remaining warnings are bolded UI labels, which the style guide requires