GitHub Issues

Open issues that describe a problem, expected result, and reproduction steps instead of dumping a vague complaint.

Issues are GitHub, not Git

GitHub Repository created a hosted project. GitHub Issues is the tracker on that GitHub page: bugs, tasks, and feature requests as conversation threads with numbers. Git stores commits. There is no git issue command. An issue does not appear in git log.

A GitHub Fork has its own Issues tab. Practice on a repository you own (the disposable remote from GitHub Repository, or your fork). Do not file practice tickets on the original project.

Search before you open a duplicate

On the GitHub Issues tab, search by keywords from the failure before you create. Duplicate reports split screenshots and workarounds across threads. If you find an existing issue, add a reproduction that is missing—do not open a second copy with the same title.

gh issue list shows open issues for the GitHub repository of the current directory. Filter before you type a new title.

Problem, expected result, reproduction

A useful bug issue has three parts a stranger can use:

## Problem
The Save button on /settings does nothing on the first click. A second click stores the name.

## Expected result
One click should save and show "Saved".

## Reproduction
1. Open https://example.test/settings while signed in.
2. Change the display name to "Ada".
3. Click Save once.
4. Reload. The name is still the previous value.

## Environment
Chrome 128, macOS, public demo account.

Feature requests still need a problem and an expected result. “Add dark mode” is thinner than “Night-shift users cannot read the contrast on the settings form; expected a theme that keeps body text above WCAG AA.” Tasks (“write the README clone section”) can be shorter, but they still name the done state.

Create the issue on a repo you own

# From a clone of a GitHub repository YOU own
gh issue create --title "Save button ignores the first click on /settings" --body "$(cat <<'EOF'
## Problem
The Save button on /settings does nothing on the first click.

## Expected result
One click should save and show Saved.

## Reproduction
1. Open /settings while signed in.
2. Change the display name.
3. Click Save once.
4. Reload. The previous name is still stored.
EOF
)"

The website New issue button is the same object: title plus body on that GitHub repository. Use gh issue create from a clone whose origin is a repository you can write to. If GitHub offers a template, fill the template; do not delete the sections that ask for reproduction.

# Do not file this. It has no expected result and no reproduction.
gh issue create --title "broken" --body "it doesn't work please fix"

That command “works” and still fails the lesson. GitHub will store the issue. Nobody can reproduce it. Rewrite it with an expected result and numbered steps before you call the report done.

List, view, and close without a pull request

gh issue list
gh issue view 1
gh issue close 1 --comment "Cannot reproduce on main after clearing localStorage."

gh issue view 1 prints the body so you can check whether a stranger would understand it. Close an issue from the GitHub UI or with gh issue close when the problem is gone or was never real. Linking a later pull request with Closes #12 is a GitHub convention taught in GitHub Pull Requests; this workshop stops at a complete report you can close by hand.

What not to put in an issue

Guided practice: one complete report

1. 01
   Pick a repository you own

   Use the practice remote from GitHub Repository, or another public repo under your account. Confirm git remote -v points at that URL.

2. 02
   Search and list

   Run gh issue list. Open the Issues tab in the browser. Confirm you are not about to duplicate an existing thread.

3. 03
   Write the three parts

   Problem, expected result, numbered reproduction. Invent a realistic bug on that disposable repo if the project has none.

4. 04
   Create and read it back

   gh issue create or New issue. Then gh issue view and ask whether a stranger could follow the steps.

5. 05
   Close it yourself

   This is practice. Close the issue with a one-line comment. Do not open a pull request.

Independent lab: issue report

1. On a GitHub repository you own, search existing issues, then open one new issue.
2. The body must include a problem, an expected result, and numbered reproduction steps.
3. Show gh issue list including that issue, and gh issue view of its number.
4. Write four lines: repository URL, issue number, why the title is specific, and which GitHub page is not a Git command.
5. Close the practice issue. Do not file it on a project you do not maintain, and do not open a pull request.

Common issue mistakes

Lesson review

You can open a GitHub issue that a stranger can act on, keep Git commits distinct from the tracker, and practice without spamming another project. The next lesson publishes a static site with GitHub Pages.

• I know a GitHub issue is a tracker item, not a Git command or a commit.
• I can write a problem, expected result, and reproduction instead of a vague complaint.
• I can gh issue list, gh issue create, and gh issue view on a repository I own.
• I do not file practice issues on projects I do not maintain, and I do not open a pull request in this lesson.