diff --git a/docs.json b/docs.json index 615442a93..64200f78f 100644 --- a/docs.json +++ b/docs.json @@ -53,6 +53,7 @@ "openhands/usage/use-cases/cobol-modernization", "openhands/usage/use-cases/dependency-upgrades", "openhands/usage/use-cases/daily-workflow", + "openhands/usage/use-cases/software-factory", "openhands/usage/use-cases/spark-migrations" ] }, diff --git a/openhands/static/img/software-factory/automations.png b/openhands/static/img/software-factory/automations.png new file mode 100644 index 000000000..7a21e436d Binary files /dev/null and b/openhands/static/img/software-factory/automations.png differ diff --git a/openhands/static/img/software-factory/completed.png b/openhands/static/img/software-factory/completed.png new file mode 100644 index 000000000..35f3f0d4e Binary files /dev/null and b/openhands/static/img/software-factory/completed.png differ diff --git a/openhands/static/img/software-factory/developer.png b/openhands/static/img/software-factory/developer.png new file mode 100644 index 000000000..0e0229bc3 Binary files /dev/null and b/openhands/static/img/software-factory/developer.png differ diff --git a/openhands/static/img/software-factory/model.png b/openhands/static/img/software-factory/model.png new file mode 100644 index 000000000..9e722d177 Binary files /dev/null and b/openhands/static/img/software-factory/model.png differ diff --git a/openhands/static/img/software-factory/profile.png b/openhands/static/img/software-factory/profile.png new file mode 100644 index 000000000..522255fd7 Binary files /dev/null and b/openhands/static/img/software-factory/profile.png differ diff --git a/openhands/static/img/software-factory/profiles.png b/openhands/static/img/software-factory/profiles.png new file mode 100644 index 000000000..e87152fd9 Binary files /dev/null and b/openhands/static/img/software-factory/profiles.png differ diff --git a/openhands/static/img/software-factory/reviewer.png b/openhands/static/img/software-factory/reviewer.png new file mode 100644 index 000000000..ded7d15e7 Binary files /dev/null and b/openhands/static/img/software-factory/reviewer.png differ diff --git a/openhands/static/img/software-factory/secrets.png b/openhands/static/img/software-factory/secrets.png new file mode 100644 index 000000000..b31a4adb2 Binary files /dev/null and b/openhands/static/img/software-factory/secrets.png differ diff --git a/openhands/static/img/software-factory/setup.gif b/openhands/static/img/software-factory/setup.gif new file mode 100644 index 000000000..3d7111efb Binary files /dev/null and b/openhands/static/img/software-factory/setup.gif differ diff --git a/openhands/static/img/software-factory/triage.png b/openhands/static/img/software-factory/triage.png new file mode 100644 index 000000000..6e06fcd6a Binary files /dev/null and b/openhands/static/img/software-factory/triage.png differ diff --git a/openhands/static/img/software-factory/watchdog.png b/openhands/static/img/software-factory/watchdog.png new file mode 100644 index 000000000..02e6bce49 Binary files /dev/null and b/openhands/static/img/software-factory/watchdog.png differ diff --git a/openhands/usage/use-cases/overview.mdx b/openhands/usage/use-cases/overview.mdx index b0c408384..5688e0cc0 100644 --- a/openhands/usage/use-cases/overview.mdx +++ b/openhands/usage/use-cases/overview.mdx @@ -8,6 +8,13 @@ OpenHands supports a wide variety of software development tasks. Here are some o Each use case can be implemented in different ways—as a one-off conversation, a scheduled [automation](/openhands/usage/automations/overview), a [plugin](https://github.com/OpenHands/extensions), or through the [SDK](/sdk/index). Pick the approach that fits your workflow. + + Take GitHub issues through development, independent review, testing, and merge with four automations. + + Step-by-step Canvas setup: model, scoped profiles, and four independent automations + + + +This walkthrough requires Agent Canvas 1.24.0 or later, which supports agent profiles in automations and [per-conversation Docker containers](/openhands/usage/agent-canvas/backend-setup/docker-execution). + + +## Before You Start + +Use an Agent Canvas backend with Automation enabled and bounded Docker workspaces. Prepare a GitHub repository with clear test commands and three repository-scoped [fine-grained personal access tokens](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens): + +| Token | Repository permissions | +| --- | --- | +| Triage | Contents: read. Issues: read and write. | +| Developer | Contents, Issues, Pull requests: read and write. Actions, Commit statuses: read. | +| Reviewer | Contents and Actions: read. Issues, Pull requests, Commit statuses: read and write. | + +Metadata read access is included by GitHub. The watchdog reuses the developer token. The reviewer can publish findings and statuses but cannot push code. Add Workflows write permission to the developer token only if agents need to change GitHub Actions workflow files. + +## Configure Canvas + + + + In the welcome screen, choose OpenHands, then configure your model and API key. For an OpenAI-compatible provider, use `Advanced` to enter the model name and base URL. Save and close the welcome screen. + + Advanced model settings with the API key hidden + + + Open `Settings` → `Secrets` → `Add a new secret`. Save: + + - `FACTORY_GITHUB_TRIAGE_TOKEN` + - `FACTORY_GITHUB_DEVELOPER_TOKEN` + - `FACTORY_GITHUB_REVIEWER_TOKEN` + + Keep token values in this secret store. Automation forms use their names. + + + Open `Settings` → `Agent` → `Add agent profile`. Select your saved model. Under `Secrets`, choose `Choose secrets` and select only the token for that role. Use `Choose servers` with no MCP servers for these GitHub workflows, and disable model switching and sub-agents. + + | Profile | Selected secret | + | --- | --- | + | `factory-triage` | `FACTORY_GITHUB_TRIAGE_TOKEN` | + | `factory-developer` | `FACTORY_GITHUB_DEVELOPER_TOKEN` | + | `factory-reviewer` | `FACTORY_GITHUB_REVIEWER_TOKEN` | + Triage profile with only the triage token selected + + + +## Add the Four Automations + +Open `Automate` → `Templates`, search for each template below, and choose `Continue with local setup`. Each scanner resolves the saved token named in its form. The triage, developer, and reviewer profiles independently restrict what their delegated agents receive. + +For every automation, add your `owner/repo`, set `Check frequency` to `*/5 * * * *`, and enter the matching **GitHub token secret name**. Select the matching agent profile for triage, development, and review. The watchdog is deterministic and starts no agent, so leave its profile empty. Select `Continue`, inspect the summary, then `Confirm and create`. New automations start enabled; turn them off until all four are configured. + + + + Select `factory-triage`. It prioritizes issues, checks dependencies, and establishes acceptance criteria before applying `ready-for-dev`. + + Triage automation confirmation + + + Select `factory-developer`. Set `Trigger label` to `ready-for-dev`, `Branch prefix` to `factory/issue`, and `Pull request mode` to `Ready for review`. + + Developer automation confirmation with the readiness label and branch prefix + + + Select `factory-reviewer`, keep `Trigger label` as `openhands-review`, and choose the desired review tone. The reviewer checks out the exact PR head, follows the repository's guidance, runs its relevant tests, posts a readable native review, and records exact-head review and test statuses. + + Reviewer automation summary with the trigger label, review tone, and reviewer token secret + + + Leave the agent profile empty, select the developer secret, and use the same `factory/issue` prefix. It merges only a current branch with passing independent acceptance statuses and passing Actions runs when present. + + Watchdog confirmation using the developer token and matching branch prefix + + + +## Start and Observe + +Turn on all four automations. Open a small GitHub issue with observable acceptance criteria. Use `Run now` to start triage immediately, or wait for the schedule. + +In `Automate`, open each automation to inspect its selected profile and activity. Follow the issue's development PR, readable review and exact-head test statuses, and final merge. Failed checks lead to revisions and fresh acceptance of the changed commit. Use the automation toggle to pause new scheduling while inspecting a problem. + +The walkthrough targets [neubig/airbnb-clone](https://github.com/neubig/airbnb-clone). In the recorded current-head deployment, six issues were triaged and six developers ran concurrently in Docker. Reviewer agents tested and accepted [PR #87](https://github.com/neubig/airbnb-clone/pull/87) through [PR #92](https://github.com/neubig/airbnb-clone/pull/92), and the watchdog merged all six. The final two reviews resumed after a graceful Canvas restart; when earlier merges made an accepted branch stale, the watchdog updated it and waited for a fresh exact-head review before merging. The earlier factory completed [neubig/box-clone](https://github.com/neubig/box-clone) through the same automated development, review, testing, and acceptance path. + +Canvas automation dashboard with all four automations active, no failures, and recent factory activity