# How to Report a Bug in OpenWork: The Complete Guide to GitHub Issues

> Learn how to report a bug in OpenWork using GitHub Issues. This guide covers the structured template and submission methods via web or CLI for efficient bug reporting.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-08-20

---

**OpenWork uses GitHub Issues with a structured bug report template, and you can submit reports either through the web interface or the GitHub CLI.**

The `different-ai/openwork` repository provides a standardized bug-reporting workflow designed to help maintainers reproduce and fix issues quickly. This guide walks through the exact steps, file locations, and tools you need to submit effective bug reports.

## The OpenWork Bug Reporting Process

OpenWork follows a template-driven approach defined in [`.github/ISSUE_TEMPLATE/bug.yml`](https://github.com/different-ai/openwork/blob/main/.github/ISSUE_TEMPLATE/bug.yml). The repository's [`SUPPORT.md`](https://github.com/different-ai/openwork/blob/main/SUPPORT.md) file documents the full workflow, which consists of five key steps:

1. **Search existing issues** — Check if your bug has already been reported.
2. **Open a new issue** — Select the "Bug report" template.
3. **Fill required sections** — Complete *Summary*, *To Reproduce*, *Expected behavior*, and *Actual behavior*.
4. **Add optional data** — Include screenshots, OpenWork version, OS details, and additional context.
5. **Submit** — The issue receives the `bug` label automatically and enters the triage queue.

The template enforces this structure by rendering form fields in the GitHub web interface, ensuring every report contains the information maintainers need to investigate.

## Submitting a Bug Report via the Web UI

The most common method uses GitHub's built-in issue creator:

1. Navigate to the **Issues** tab of the `different-ai/openwork` repository.
2. Click **New issue** → select **Bug report**.
3. Fill in the sections rendered by the template from [`.github/ISSUE_TEMPLATE/bug.yml`](https://github.com/different-ai/openwork/blob/main/.github/ISSUE_TEMPLATE/bug.yml).
4. Optionally attach screenshots or screen recordings.
5. Click **Submit new issue**.

## Creating a Bug Report Using the GitHub CLI

For command-line workflows, use the `gh` tool to create pre-populated bug reports:

```bash

# Create a temporary markdown file with the required sections

cat <<'EOF' > bug_report.md

### Summary

<!-- What is not working? -->

### To Reproduce

1. <!-- Step 1 -->
2. <!-- Step 2 -->
3. <!-- Step 3 -->

### Expected behavior

<!-- What you expected to happen -->

### Actual behavior

<!-- What actually happened -->

### Desktop info (optional)

- OpenWork version: 0.1.166
- OS: macOS 14.2
EOF

# Open a new GitHub issue using the Bug template

gh issue create \
  --title "[Bug]: Brief description of the problem" \
  --body-file bug_report.md \
  --label bug

```

This approach requires the GitHub CLI installed and authenticated. The `--label bug` flag ensures consistent tagging with web-submitted reports.

## Understanding the Bug Report Template Structure

The [`.github/ISSUE_TEMPLATE/bug.yml`](https://github.com/different-ai/openwork/blob/main/.github/ISSUE_TEMPLATE/bug.yml) file defines the structured form that appears when you select "Bug report." According to the OpenWork source code, this template specifies:

- **Required fields** that must be completed before submission
- **Reproduction steps** with numbered list formatting
- **Behavior comparison** sections for expected vs. actual results
- **Optional diagnostic fields** for version and environment details

Because the template lives in the repository, you can reference it directly or copy its structure locally to draft reports before creating the issue.

## Key Files for Bug Reporting in OpenWork

| File | Purpose | Location |
|------|---------|----------|
| [`.github/ISSUE_TEMPLATE/bug.yml`](https://github.com/different-ai/openwork/blob/main/.github/ISSUE_TEMPLATE/bug.yml) | Defines the structured bug-report template used for every new bug issue | `dev` branch |
| [`SUPPORT.md`](https://github.com/different-ai/openwork/blob/main/SUPPORT.md) | Provides high-level guidance on where and how to ask for help, including bug-reporting instructions | `dev` branch |

Both files are maintained in the `dev` branch of the `different-ai/openwork` repository.

## Best Practices for Effective Bug Reports

**Be specific in reproduction steps.** The `To Reproduce` section in the bug report template exists because maintainers need exact sequences to trigger the same behavior.

**Include version information.** The optional `Desktop info` section in the template captures OpenWork version and operating system—details that often explain environment-specific bugs.

**Attach visual evidence.** Screenshots or short videos clarify UI issues faster than text descriptions alone.

## Summary

- OpenWork uses **GitHub Issues** with a **structured bug report template** defined in [`.github/ISSUE_TEMPLATE/bug.yml`](https://github.com/different-ai/openwork/blob/main/.github/ISSUE_TEMPLATE/bug.yml)
- The **SUPPORT.md** file documents the complete bug-reporting workflow
- Reports require four core sections: **Summary**, **To Reproduce**, **Expected behavior**, and **Actual behavior**
- You can submit via **web UI** or **GitHub CLI** with the `gh issue create` command
- All bug reports receive automatic **labeling** and enter the project's **triage queue**

## Frequently Asked Questions

### What information is required when I report a bug in OpenWork?

The bug report template requires four sections: a brief **Summary** of the problem, numbered steps **To Reproduce** the issue, **Expected behavior** describing what should happen, and **Actual behavior** describing what occurred. Optional fields include OpenWork version, operating system, and additional context.

### Where is the bug report template defined in OpenWork?

The template is defined in [`.github/ISSUE_TEMPLATE/bug.yml`](https://github.com/different-ai/openwork/blob/main/.github/ISSUE_TEMPLATE/bug.yml) on the `dev` branch. This YAML file specifies the form fields, required sections, and automatic labeling that GitHub applies when you create a new bug report.

### Can I create a bug report without using the web interface?

Yes. Install and authenticate the GitHub CLI (`gh`), then use `gh issue create` with the `--body-file` flag to submit a pre-written report and the `--label bug` flag to ensure proper categorization. This command-line method produces issues identical to web submissions.

### How does OpenWork prevent duplicate bug reports?

The documented workflow in [`SUPPORT.md`](https://github.com/different-ai/openwork/blob/main/SUPPORT.md) instructs reporters to **search existing issues** before creating new ones. This step appears first in the recommended process, helping consolidate related reports and reduce maintainer overhead.