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

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. The repository's 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.
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:

# 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 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	Defines the structured bug-report template used for every new bug issue	dev branch
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
• 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}