← Back to articlesGitHub basics

How do you write a useful GitHub issue?

A useful issue includes environment, reproduction, expected and actual behavior, and errors.

The short answer

Search existing issues first. Remove credentials, private paths and customer details before posting logs or screenshots.

Try it in three steps

  • Reproduce the problem with minimal steps.
  • Record version and frequency.
  • Search the error and review a draft before posting.

A practice prompt

Before you start

Draft an issue for a fictional defect without posting it.

Practice material (fictional)

Practice version 0.1: open demo.html, enter whitespace and click Organize. An empty table appears without explanation every time.

Replace placeholders in the prompt with this material, or append the material if there are no placeholders. Reading time excludes doing the exercise.

Draft an issue with reproduction steps and environment placeholders. Preserve the error but redact secrets. Do not post yet.

What to look for (not a recorded test result)

Include version, steps, expected guidance and actual output. Mark other systems untested and omit private paths from logs.

If it goes wrong

Replace does not work with the failed action and exact message.

Check your result

A maintainer could reproduce it without first asking for basic details.

References and scope

The links below support the concepts or product navigation. The steps and exercises are our teaching suggestions, not official certification or measured customer outcomes. Product interfaces and availability may change. References checked on 2026-10-17.

Start with one task

Describe the current process and its slowest step. The initial conversation is free.

Let’s talk ↗
Need help? See small-scale implementation services ↗

Keep reading