docs(factories): document GitHub integration - #526
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
495ccc7 to
de51e36
Compare
de51e36 to
59a24f2
Compare
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment 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}
There was a problem hiding this comment.
Overview
This PR replaces the placeholder factory GitHub integration page with provider-specific documentation for setup, triggers, filters, continuation, outputs, and troubleshooting. The page is generally scannable, but the diff still has one product-accuracy issue around best-effort label cleanup and two docs-style issues.
Concerns
- The label-management section describes best-effort cleanup as guaranteed, which can mislead readers if a repository label remains after repository removal or factory deletion.
- The first UI procedure should orient readers to the product surface before naming the setup flow.
- The filter list should format filter names consistently as UI elements.
- No approved repository spec context was provided, so no spec-drift findings were evaluated. The documentation-only diff introduced no security findings.
Verdict
Found: 0 critical, 1 important, 2 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
There was a problem hiding this comment.
Overview
This PR replaces the placeholder factory GitHub integration page with provider-specific documentation for setup, triggers, filters, continuation, outputs, and troubleshooting. The page is generally scannable, but the diff still has one product-accuracy issue around best-effort label cleanup and two docs-style issues.
Concerns
- The label-management section describes best-effort cleanup as guaranteed, which can mislead readers if a repository label remains after repository removal or factory deletion.
- The first UI procedure should orient readers to the product surface before naming the setup flow.
- The filter list should format filter names consistently as UI elements.
- No approved repository spec context was provided, so no spec-drift findings were evaluated. The documentation-only diff introduced no security findings.
Verdict
Found: 0 critical, 1 important, 2 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review 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 replaces a placeholder with a full factory-specific GitHub integration page covering prerequisites, triggers, filters, continuity, writeback, and troubleshooting. The page is broadly scoped and security-conscious, but two changed lines need correction before merge.
Concerns
- The new setup prerequisite uses a relative link across Starlight topic spaces; repository guidance requires absolute docs URLs for cross-space links.
- The label lifecycle note starts with best-effort phrasing but then describes label cleanup as guaranteed, which can set the wrong expectation for users.
Verdict
Found: 0 critical, 1 important, 1 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
59a24f2 to
f57ce3f
Compare
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review 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 replaces the placeholder Factory GitHub integration page with a focused documentation page covering setup, supported GitHub triggers, filters, continuity, outputs, authorization boundaries, and troubleshooting. The change is docs-only, has no approved spec context to compare against, and the supplemental security pass found no security-specific issues.
Concerns
- One internal docs link points at the production
docs.warp.devdomain instead of an internal docs route, so preview/staging builds would send readers out of the current build.
Verdict
Found: 0 critical, 0 important, 1 suggestions
Approve with nits
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
f57ce3f to
efdcaf0
Compare
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review 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 replaces the placeholder Factory GitHub integration page with factory-specific guidance for GitHub App authorization, repository selection, automation triggers, filters, continuity, outputs, factory-definition checks, and troubleshooting.
Concerns
No blocking correctness, documentation-structure, security, or spec-drift concerns were found in the attached diff. The diff adds no code comments or tests to audit, and the provided spec context states that no approved or repository spec context was found.
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
|
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 replaces the placeholder factory GitHub integration page with substantive guidance for connecting factories to GitHub, configuring automations, understanding supported triggers, and troubleshooting operational boundaries. I did not find security findings or applicable spec-drift concerns in the attached context.
Concerns
- One minor UI-label formatting issue should be adjusted so the documentation does not imply the label includes sentence punctuation.
Verdict
Found: 0 critical, 0 important, 1 suggestions
Approve with nits
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
efdcaf0 to
6ec2035
Compare
|
/oz-review |
Co-Authored-By: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Co-Authored-By: Warp <agent@warp.dev>
Review feedback addressed: - Rewrite intro sentence to remove passive framing (per suggestion). - Tighten prerequisites bullets; clarify what 'covered by the app installation' means for the factory-repos prerequisite. - Fix the setup step to name the actual web app, URL, and UI element (+ next to Factories) that opens the setup wizard, matching quickstart.mdx's established terminology. - Link 'control room' to its doc page and use 'click' instead of 'open' for Automations. - Split the overloaded triggers/event/repo/filters step into three separate steps. - Widen the Supported triggers table's first column so multi-word entries (Pull requests, Code and CI) stop wrapping. - Apply suggested rewrites for the CI payloads sentence, the mention/assignment step, the mentions-routing sentence, and the final review/merge-adjacent permissions bullet (dropping em dashes and colons). - Rewrite 'the factory reacts to the activity it handles' to remove the redundant framing. Left as-is per explicit instruction: the @oz-agent vs @warp handle suggestion, pending confirmation from other reviewers. Additionally reviewed the full file top to bottom for brevity: trimmed the prerequisites bullet, the default-automations sentence, the mentions/ignored sentence, the continuing-work-item sentence, and significantly condensed the factory-definition pull request checks paragraph (removed an em-dash asparagraph (removed an em-dash asparagraph (removed an em-dash adev>
…tighten github.mdx The page said the second default automation is "one that closes or merges pull requests." It triggers on a pull request closing or merging: on a merge it completes the work items linked from the pull request, and on a close without a merge it exits without side effects. Also drop the "when Linear or Jira is connected" qualifier, since the prompt is provider-neutral and resolves each linked item's tracker from its URL at run time, and trim the prerequisites, label lifecycle, and permissions copy per review feedback. Co-Authored-By: Warp <agent@warp.dev>
…tories-integration-github # Conflicts: # src/content/docs/factories/integrations/github.mdx
MaggieShan
left a comment
MaggieShan
left a comment
There was a problem hiding this comment.
overall LGTM sorry for the delay!
| A factory doesn't get its own GitHub handle. Every factory listens through the same Warp agent account, **@oz-agent**, and the factory's `factory:<alias>` label decides which factory a mention reaches: | ||
|
|
||
| 1. Apply the factory's `factory:<alias>` label to the issue or pull request. Warp creates the label in each connected repository. | ||
| 2. Assign **@oz-agent** to the issue or pull request, or mention **@oz-agent** in the body or in any new comment. |
There was a problem hiding this comment.
to further confirm - this will/should be @warp-factory instead of oz-agent
There was a problem hiding this comment.
Confirmed and changed to @warp-factory, in both this line and the assign/mention step below it. Since this PR had already merged, it landed in #562.
Thanks for pushing on this — Rachael raised the same doubt earlier and I initially told her @oz-agent was correct, because it is what production resolves to today (config/github.go defaults to it, and only local.yaml and staging.yaml override). What I'd missed was warp-server#15306, which gives factories their own permanently separate handle: FactoryGitHubHandle() is documented as "permanently distinct from GitHubAgentHandle(): callers pick whichever applies, never fall back between them", and githubSeedAutomations materializes it into the seeded mention and assignment filters.
One thing worth flagging: #15306 is still an open draft and now has merge conflicts, and the behavior is gated behind a factory_github_handle flag. So the docs now lead the server. That's harmless while #508 is unmerged and these pages aren't public, but #15306 needs to land before #508 reaches main, or the page will name a handle that doesn't answer. Flagging in case that ordering isn't already on someone's radar.
There was a problem hiding this comment.
Your GitHub account is not connected to Warp. Connect it here.
|
|
||
| 1. In the {VARS.FACTORY_WEB_APP} at <a href={VARS.FACTORY_WEB_APP_URL}>platform.warp.dev</a>, click **+** next to **Factories** to open the setup wizard, then choose **I want to use repos from GitHub** under **Connect your code host**. | ||
| 2. Under **Select your repos**, choose the repositories to provide code and context for the factory. | ||
| 3. In the factory's [control room](/factories/control-room/), click **Automations**. Create an automation or edit a default one, choose the receiving agent, and add any **Additional instructions**. |
There was a problem hiding this comment.
We populate default github automations on factory creation - so this is technically not required (or could maybe be it's own section for adding automations in general?)
There was a problem hiding this comment.
Good catch, and I think the old shape was worse than just redundant — it was misleading. A seven-step procedure where five of the steps build an automation by hand implies the factory sits idle until you configure a trigger, when it's actually already listening the moment you connect.
Restructured in #562 along the lines you suggested:
- Connect GitHub to a factory is now the two steps it actually takes, followed by what the two seeded defaults already do and a one-line way to verify (mention the factory on a test issue, watch for a work item).
- Add a custom automation is its own section, framed for the cases the defaults don't cover, like a failed CI run or a review request.
I confirmed the seeding claim against githubSeedAutomations in logic/factorysource/defaults/automations.go before rewording, so the page now matches when those automations actually appear.
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>
* docs(factories): bridge factory:<alias> to the Foreman name label on 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> * docs(factories): address Maggie's review on the GitHub page 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> --------- Co-authored-by: Warp <agent@warp.dev>
4 participants
Summary
Adds factory-specific GitHub documentation covering App installation scope, repositories, issue/PR/review/CI triggers, filters, event-author identity, continuity, branches and pull requests, writeback, and separate factory-definition validation checks.
Final size: 890 prose words. Generic provider installation details remain in the existing platform integration page; this PR focuses only on factory-specific behavior.
Foundation
Shared navigation, route placeholders, Early Access badge support, and guide migrations are merged in #537. This PR now contains only its feature-owned files and passes CI independently.
Validation
npm run typecheck: 0 errorsnpm run build: 377 pages builtLatest source refresh
Adds best-effort GitHub factory: label creation/removal while preserving installation and event-author credential boundaries.
Verified against Warp
e72fd7aacand warp-server9be39e484b. Broken, placeholder, partial, and spec-only surfaces remain excluded.Proposed reviewers
Based on the Warp Factories Soft Launch (August 18th) tracker. For planning only; no review requests have been sent.
@MaggieShan@IsaiahWitzke@moirahuangScreenshots
Not included. The page uses a compact trigger/context/output table and links to the existing provider setup page; no approved factory-specific UI assets exist yet.
Unverified claims
None — UI labels, event classes, filters, authorization boundaries, continuity, and writeback behavior were verified against source.
Conversation: https://staging.warp.dev/conversation/5ff89820-2d80-4518-981e-178845029de1
Plans: https://staging.warp.dev/drive/notebook/7ZPKWz7hM5I59o4Gg2ptYi and https://staging.warp.dev/drive/notebook/DpRWhMQ0DLCajPPMggXw5e
Co-Authored-By: Warp Agent agent@warp.dev