An issue is a trackable unit of work or discussion — typically a bug report, a feature request, a question, or a task — created inside a repository on a hosting platform such as GitHub, GitLab, or Bitbucket. It has a title, a description, a status (open or closed), and a running comment thread where people discuss it over time. Critically, an issue is not stored inside Git’s own data structures at all; it lives in the hosting platform’s separate database.

Picture a concrete example: a user of a mobile app notices that the login screen crashes on older phones. They open the app’s GitHub repository and click “New Issue,” writing a title like “App crashes on login for Android 9 devices” along with steps to reproduce it. A maintainer replies asking for a screen recording. Another contributor comments that they can reproduce it and offers a possible fix. Eventually, someone submits a pull request that resolves the bug and references the issue, which then automatically closes. None of this — the title, the comments, the open/closed status — is stored as a Git commit or object; it all lives in the platform’s issue-tracking system.

Because issues live entirely on the hosting platform’s side, the mechanism resembles a typical web application’s data model far more than anything inside Git. Here’s what actually happens when an issue is created and later referenced from code.

flowchart LR
    A["Issue opened\n(bug, feature, question)"] --> B["Open status"]
    B --> C["Discussion via\ncomments"]
    C --> D["Contributor writes\ncode fix"]
    D --> E["Pull request opened\nwith 'Fixes #N'"]
    E --> F{"PR merged?"}
    F -->|"Yes"| G["Issue auto-closed"]
    F -->|"No / rejected"| C
    B -->|"No fix needed"| H["Manually closed"]
    

Notice that closing an issue can happen two ways: automatically, when a linked pull request with a closing keyword gets merged, or manually, when a maintainer decides the issue doesn’t need code changes — perhaps it was a duplicate, a misunderstanding, or something intentionally left as-is. Both paths end the same way (status becomes “closed”), but only the automatic path creates a permanent, visible link between the issue and the exact commit that resolved it.

A well-formed issue is made up of several distinct parts, each serving a specific organizational purpose. Understanding them helps you both write better issues and navigate a busy repository’s issue tracker efficiently.

• Write a clear, specific title. “Button doesn’t work” helps no one; “Submit button on checkout page doesn’t respond on Safari 17” gets fixed faster.
• Use an issue template for bug reports. Requiring reproduction steps, expected vs. actual behavior, and environment details drastically cuts back-and-forth clarification.
• Keep one issue per problem. Bundling five unrelated bugs into a single issue makes it nearly impossible to close cleanly or track progress accurately.
• Always link the fixing pull request. Using closing keywords like “Fixes #42” keeps the connection between discussion and code fully automatic and auditable.
• Triage regularly. Close duplicates, label new issues promptly, and periodically review old ones that may no longer be relevant — an untriaged tracker quickly becomes unusable.