Whether you’re reporting a bug, suggesting a feature, or starting a discussion, GitHub Issues provide a powerful way to collaborate on software projects. Issues are an essential part of any open-source or team workflow, helping keep track of tasks, enhancements, and problems.
In this post, we’ll walk you through how to create a new issue on GitHub — step by step.
🧠 What is a GitHub Issue?
A GitHub issue is a lightweight way to track:
- Bugs and defects
- Feature requests
- To-dos or project tasks
- Documentation improvements
- General questions or discussions
Each issue is tied to a specific repository and can include labels, assignees, milestones, and comments for collaboration.
✅ Prerequisites
Before you can create an issue:
- You must be logged into your GitHub account.
- The repository must have Issues enabled.
💡 For private or organization repositories, you may need appropriate permissions to open an issue.
🛠️ How to Create a New Issue
Step 1: Navigate to the Repository
Go to the GitHub repository where you want to open an issue.
Example: https://github.com/owner-name/repo-name
Step 2: Click on the “Issues” Tab
At the top of the repo page, click the “Issues” tab (next to “Code”, “Pull requests”, etc.).
Step 3: Click “New Issue”
Click the green “New issue” button on the right-hand side of the screen.
Step 4: Fill in the Issue Details
- Title: A short, descriptive summary of the issue.
- Description: Provide detailed information. Include:
- Steps to reproduce (for bugs)
- Expected vs. actual behavior
- Screenshots or error messages
- Links or related context
Some repositories provide issue templates that guide you on what to include — just follow the prompts.
Step 5: (Optional) Add Labels, Assignees, or Projects
If you have the right permissions, you can:
- Add labels to categorize the issue (e.g.,
bug,enhancement,question) - Assign the issue to a contributor
- Add it to a project board or milestone
Step 6: Submit the Issue
Click the “Submit new issue” button — and you’re done!
Your issue will now be visible in the repository’s Issues section, and others can comment, react, or start working on it.
📌 Tips for Writing a Good Issue
- Be specific and detailed.
- Use markdown formatting to structure your text (e.g., lists, code blocks).
- Search existing issues to avoid duplicates.
- Include logs, screenshots, or links where applicable.
🔐 Can You Create Issues on Any Repository?
For public repositories, yes — unless the owner has disabled the Issues tab or blocked access.
For private repositories, you must be a collaborator or team member.
📋 Summary
| Step | Action |
|---|---|
| Navigate to repo | Go to github.com/user/repo |
| Open Issues tab | Click the “Issues” tab |
| Create new issue | Click “New issue” |
| Fill in title and body | Describe your problem or request |
| Submit | Click “Submit new issue” |
🚀 Final Thoughts
GitHub Issues are a core part of collaborative development. Whether you’re filing bugs, requesting features, or coordinating tasks, issues help keep everyone on the same page.
If you’re contributing to an open-source project, creating well-written issues is one of the best ways to start.