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

> Easily report bugs in OpenWork using GitHub Issues. Follow our guide to fill out the bug report template with clear steps and observations for quick resolution.

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

---

**Report bugs in OpenWork by opening a GitHub Issue using the Bug report template, which requires specific sections like Summary, Steps to Reproduce, and Expected vs Actual behavior.**

The OpenWork repository (`different-ai/openwork`) uses structured GitHub Issues to track defects. When you encounter unexpected behavior, the project provides standardized templates and documentation to ensure maintainers can quickly reproduce and resolve your issue.

## Using the Bug Report Template

OpenWork enforces a structured format for all bug reports through the **Bug report** template. This template is defined in [`.github/ISSUE_TEMPLATE/bug.yml`](https://github.com/different-ai/openwork/blob/main/.github/ISSUE_TEMPLATE/bug.yml) and automatically populates the issue form with required fields when you select it from the GitHub web interface.

### Required Fields

Every bug report must include these core sections to be actionable:

- **Summary** – A concise description of what is malfunctioning
- **To Reproduce** – Numbered steps that consistently trigger the bug
- **Expected behavior** – What you anticipated should happen
- **Actual behavior** – What actually occurred, including error messages

### Optional Diagnostic Information

The template also collects optional metadata that accelerates triage:

- **OpenWork version** – The specific release or commit hash (e.g., `0.1.166`)
- **Operating system** – Your OS and version (e.g., macOS 14.2)
- **Screenshots or recordings** – Visual evidence of the defect
- **Additional context** – Any other relevant configuration details

## Step-by-Step Bug Reporting Workflow

According to the project's [`SUPPORT.md`](https://github.com/different-ai/openwork/blob/main/SUPPORT.md) file, follow this standardized process to ensure your report reaches the triage queue efficiently:

1. **Search existing issues** – Verify the bug hasn't already been reported to avoid duplicates.
2. **Open a new issue** – Navigate to the Issues tab and select the **Bug report** template.
3. **Fill out required sections** – Complete the Summary, To Reproduce, Expected behavior, and Actual behavior fields with precise details.
4. **Add optional data** – Include your OpenWork version, OS details, screenshots, and any environment-specific context.
5. **Submit** – The issue will be automatically labeled `bug` and added to the maintainers' triage queue.

## Creating Bug Reports Programmatically

You can generate bug reports from the command line using the GitHub CLI (`gh`). This approach allows you to draft the report locally using the standard template structure before submitting.

Create a temporary markdown file with the required sections:

```bash
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

```

Submit the issue using the `gh` command with the bug label:

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

```

## Key Files for Bug Reporting

Two files in the repository define the bug reporting standards:

- **[`.github/ISSUE_TEMPLATE/bug.yml`](https://github.com/different-ai/openwork/blob/main/.github/ISSUE_TEMPLATE/bug.yml)** – Defines the structured form fields and automatic labeling logic used for every new bug issue.
- **[`SUPPORT.md`](https://github.com/different-ai/openwork/blob/main/SUPPORT.md)** – Contains high-level guidance on where to seek help and detailed instructions for submitting effective bug reports.

## Summary

- OpenWork tracks defects exclusively through **GitHub Issues** using a standardized template defined in [`.github/ISSUE_TEMPLATE/bug.yml`](https://github.com/different-ai/openwork/blob/main/.github/ISSUE_TEMPLATE/bug.yml).
- Every bug report requires four essential sections: **Summary**, **Steps to Reproduce**, **Expected behavior**, and **Actual behavior**.
- The [`SUPPORT.md`](https://github.com/different-ai/openwork/blob/main/SUPPORT.md) file documents the complete workflow, which includes searching existing issues, selecting the correct template, and providing diagnostic metadata.
- Issues created via the template are automatically labeled `bug` and routed to the triage queue.
- You can submit reports programmatically using the `gh` CLI with a markdown file structured according to the template requirements.

## Frequently Asked Questions

### What information is mandatory when reporting a bug in OpenWork?

You must provide a **Summary** of the problem, specific **Steps to Reproduce**, the **Expected behavior**, and the **Actual behavior** observed. These four fields are required in the [`.github/ISSUE_TEMPLATE/bug.yml`](https://github.com/different-ai/openwork/blob/main/.github/ISSUE_TEMPLATE/bug.yml) template and ensure maintainers can replicate the issue.

### How do I avoid creating duplicate bug reports?

Search the existing **Issues** tab in the `different-ai/openwork` repository using keywords related to your problem. The [`SUPPORT.md`](https://github.com/different-ai/openwork/blob/main/SUPPORT.md) file explicitly lists this as the first step in the bug reporting workflow to prevent redundant tickets.

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

Yes. You can use the **GitHub CLI (`gh`)** to create issues from the command line. Create a markdown file containing the required sections (Summary, To Reproduce, Expected behavior, Actual behavior) and run `gh issue create --body-file yourfile.md --label bug`.

### Where are the bug report templates stored?

The structured bug report template lives in [`.github/ISSUE_TEMPLATE/bug.yml`](https://github.com/different-ai/openwork/blob/main/.github/ISSUE_TEMPLATE/bug.yml) within the repository root. This file defines the form fields, required inputs, and automatic labeling that appears when you select "Bug report" from the New Issue menu.