GitLab OpenHands Resolver Runner—Automated Issue Resolution via CI/CD

[pcuci]

I was looking for a different, potentially simpler, and more CI-native operational model for deploying and managing the OpenHands resolver functionality.

While self-hosting OpenHands Cloud is a fine option, many teams' automation world revolves around their CI/CD system.

Currently, using OpenHands to resolve issues (via openhands.resolver.resolve_issue) requires manual invocation or setting up individual CI/CD pipelines in each target repository. This becomes cumbersome and difficult to manage at scale for organizations or individuals wanting to apply OpenHands across multiple projects. There's no standardized, easy-to-deploy "runner" or "bot" CI/CD pattern that can be centrally managed and triggered by events (like labeling an issue) in various target repositories.

We propose the creation of an "OpenHands Resolver Runner," a dedicated project and set of CI/CD templates (initially for GitLab, potentially for GitHub Actions later?) inspired by the renovate-bot/renovate-runner project.

This runner would:

1. Be a Centralized Project: A standalone GitLab (or GitHub mirrored to GitLab) repository that users can fork or use as a template. This project would contain the core logic and CI/CD pipeline definitions for running the OpenHands resolver.
2. Offer Reusable CI/CD Templates: Target projects would include a CI/CD file from this runner project (e.g., /templates/openhands-resolver.gitlab-ci.yml).
3. Be Event-Triggered:
   • Primarily triggered by webhooks from target repositories when a specific label (e.g., openhands-fix-me or configurable) is added to an issue.
   • Optionally, could also be triggered by scheduled pipelines to scan for appropriately labeled issues, like renovate
4. Be Configurable via CI/CD Variables:
   • Runner Project Configuration:
     • OPENHANDS_GITLAB_TOKEN: A Personal Access Token for a bot user with necessary permissions (api, read_repository, write_repository on GitLab; contents, issues, pull-requests on GitHub).
     • OPENHANDS_LLM_API_KEY and OPENHANDS_LLM_MODEL: For LLM access.
     • OPENHANDS_TRIGGER_TOKEN: The GitLab pipeline trigger token (for the runner project itself).
     • OPENHANDS_WEBHOOK_SECRET: A shared secret to verify incoming webhooks.
     • OPENHANDS_TRIGGER_LABEL: The label that activates the resolver (e.g., openhands-fix-me).
     • OPENHANDS_TARGET_SCOPE: Defines which repositories the runner can operate on (e.g., group1/project1,group2/* or using autodiscover-like filters).
   • Target Project (Webhook Variables): Target projects would pass minimal necessary information via webhook payload or trigger variables, primarily the target repository path and issue IID.
5. Automated Workflow:
   • The runner's CI pipeline receives a trigger.
   • It authenticates/validates the trigger (e.g., webhook secret).
   • It parses the payload to identify the target project and issue.
   • It invokes the OpenHands resolver module (openhands.resolver.resolve_issue) with the appropriate arguments (target repo, issue number, tokens, LLM config).
   • The OpenHands resolver (as it currently does) clones the repo, attempts a fix, and generates a patch.
   • If successful (or an attempt is made):
     • The runner's CI job uses openhands.resolver.send_pull_request to create a new branch and open a Merge Request (MR) / Pull Request (PR) in the target repository.
     • It posts a comment on the original issue with a link to the MR/PR and a summary of the attempted fix.
     • It removes the trigger label from the issue.
   • If failed:
     • It posts a comment on the original issue detailing the failure.
     • Optionally, it could add a "openhands-fix-failed" label and remove the trigger label.
6. Support for Target-Specific Context: Allow target projects to provide .openhands/microagents/repo.md for repository-specific instructions to the OpenHands agent.

Alternatives considered

1. Manual Invocation: Running openhands.resolver.resolve_issue locally for each issue. This is not scalable for an individual maintainer contributing to multiple projects.
2. Individual CI in Each Target Repo: Each project having its own CI job to run OpenHands. This leads to duplicated CI configuration, difficulty in updating the agent version centrally, and managing secrets across many projects.
3. Long-Running Service/Bot: While possible via OpenHands Cloud [Refactor]: Update resolver instructions #8601, a CI-triggered approach (like renovate-runner) is often simpler to deploy and manage, especially for self-hosted GitLab instances, and avoids the need for persistent live infrastructure.

Additional context
The renovate-bot/renovate-runner project provides a working example of how a centralized utility can serve multiple projects through CI/CD includes and well-defined configuration. This feature request aims to generalize and productize this pattern for the wider OpenHands community active in GitLab.

The existing openhands.resolver module already contains the core logic for fetching issues, running OpenHands, and generating patches. The "runner" would be about the CI/CD orchestration, templating, webhook handling, and the final MR/PR creation and issue commenting steps, all accomplished as pipeline jobs, on a per-issue labeling event basis.

Key Benefits:

• Scalability: Easily apply OpenHands to many projects without individual setup in each.
• Centralized Management: Update the OpenHands agent version and core runner logic in one place.
• Automation: Fully automate the "label -> attempt fix -> propose MR/PR" workflow.
• Ease of Adoption: Target projects only need to include a CI template and configure a webhook.
• Security: Centralized management of sensitive tokens (LLM, Git PAT) in the runner project's CI/CD variables.

Open Questions for Discussion:

• Initial focus on GitLab CI, with GitHub Actions as a potential follow-up. In the meantime, one could use the OpenHands GitHub resolver from within a GitLab CI/CD pipeline.
• Best practices for webhook security and payload validation. This is the biggest unknown. Would improve the DX.
• Configuration options for the runner (e.g., default branch for MRs, MR title/body templates).
• How should the runner handle OpenHands versioning and updates?
• Error handling and retry strategies within the runner's CI pipeline.
• Should there be a mechanism for target projects to override certain OpenHands resolver parameters (e.g., max_iterations, llm_model) via their webhook trigger or a config file in their repo?

We believe this "OpenHands Resolver Runner" would significantly enhance the accessibility, usability and impact of OpenHands for automated code maintenance and issue resolution.

👍to upvote

[github-actions]

This issue is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.

[pcuci]

I got the "label issue to trigger OpenHands CI resolver" workflow working in GitLab, maintaining a separate fork: https://gitlab.com/deposition.cloud/apps/openhands

If you're looking for inspiration, you might be able to fork: https://gitlab.com/deposition.cloud/infra/devops/openhands

You can see here that "it worked" at some point, https://gitlab.com/deposition.cloud/apps/hello/-/boards
can't promise it will work again, as the OpenHands code changes fast

If All Hands AI and/or the OpenHands GitLab community at large wants to setup the reference pipeline independently in Gitlab, like Renovate did, I'd be happy to help and be "the first live user" of it to test it end-to-end.

Right now, https://gitlab.com/all-hands-ai seems to have disappeared 😄

[mbasaran]

I have deployed openhands on my local server and rather than forking it I created a script which uses openhands api.
This script can be run via gitlab ci/cd scheduled jobs.

How it works:

• Each time it triggers check the assigned tasks to a gitlab-bot user. This gitlab-bot user is created for openhands use and pick the issues assigned it. I am using OpenHands repo settings to integrate with gitlab and this bit user. So you can see the same tasks from both Openhands UI and from API.

• scripts launchs/triggers the assigned tasks.

• Openhands basically runs the task same as launched from UI.

With this approach, the launch script is outside openhands code and I can upgrade openhands itself whenever i want.

[github-actions]

This issue is stale because it has been open for 40 days with no activity. Remove the stale label or leave a comment, otherwise it will be closed in 10 days.

[github-actions]

This issue was automatically closed due to 50 days of inactivity. We do this to help keep the issues somewhat manageable and focus on active issues.