How to Manage GitHub Issues Using 'gh issue' (with examples)

The gh issue command is part of the GitHub CLI, which allows developers to manage and interact with GitHub issues directly from the terminal. This can be extremely useful for software developers who work with GitHub repositories and want to streamline their workflow by handling issues efficiently without opening a web browser for every single task. This document illustrates several use cases of the gh issue command, each tailored to a specific need in the software development process.

Display a Specific Issue

Code:

gh issue view issue_number

Motivation:

In a busy development environment, it’s crucial to quickly access details of a particular GitHub issue without leaving the command line. Whether you’re debugging a problem, prioritizing a backlog, or checking the status of a task, viewing the details of an issue directly from the terminal helps you stay focused and efficient.

Explanation:

• gh issue view: This command initiates the viewing of an issue within the terminal.
• issue_number: This is a placeholder for the unique number assigned to the specific issue you wish to view. Each issue in a GitHub repository is identified by its issue number.

Example Output:

#123 Bug: Application crashes on startup
Opened by user @dev1 on Oct 10, 2023
Status: Open
Labels: bug, urgent

Display a Specific Issue in the Default Web Browser

Code:

gh issue view issue_number --web

Motivation:

Sometimes visualizing an issue in a web browser provides a more comprehensive view, especially if the issue consists of long descriptions, linked pull requests, or extensive comments. Using this command, you can instantly open the issue in your web browser directly from the terminal.

Explanation:

• gh issue view: As before, this is for viewing an issue.
• issue_number: The specific number for the issue you’re interested in.
• --web: This option signals the command to display the issue in the default web browser instead of the terminal.

Example Output:

Opens the issue page in the default web browser, showing the complete details and discussions around the issue.

Create a New Issue in the Default Web Browser

Code:

gh issue create --web

Motivation:

Creating issues is an integral part of the software development workflow. This command is especially useful when you need the full functionality of the GitHub issue page, such as templates, markdown support, and multimedia attachments, which may not be available in the terminal.

Explanation:

• gh issue create: Initiates the creation of a new GitHub issue.
• --web: Directs the command to open the issue creation page in the default web browser, rather than creating it from the command line.

Example Output:

Opens the New Issue page in your default web browser, allowing you to fill in all necessary fields and submit the issue with all desired details.

List the Last 10 Issues with the bug Label

Code:

gh issue list --limit 10 --label "bug"

Motivation:

In large projects, issues labeled as bugs may arrive frequently. Filtering and listing the latest bug reports help developers prioritize and address the most recent or urgent problems quickly and efficiently.

Explanation:

• gh issue list: Lists issues from the GitHub repository.
• --limit 10: Restricts the output to the 10 most recent issues.
• --label "bug": Filters the issues to display only those with the label “bug”.

Example Output:

#240 Bug: Incorrect data rendering
#239 Bug: Null pointer exception on save
#238 Bug: UI freezes intermittently
...

List Closed Issues Made by a Specific User

Code:

gh issue list --state closed --author username

Motivation:

Tracking contributions by team members is essential for project management and evaluation. This command helps in reviewing all issues that a particular developer has closed, thus providing insights into their contributions and workload.

Explanation:

• gh issue list: Lists issues from the repository.
• --state closed: Filters issues to show only those that have been closed.
• --author username: Specifies the username whose closed issues are being queried.

Example Output:

#215 Feature: Add dark mode - Closed by @dev2
#210 Bug: Fix login error - Closed by @dev2
...

Display the Status of Issues Relevant to the User, in a Specific Repository

Code:

gh issue status --repo owner/repository

Motivation:

Keeping track of issues that are relevant to you within a specific repository can help in managing your priorities and responsibilities. This command provides a personalized view, enhancing efficiency and focus.

Explanation:

• gh issue status: Displays an overview of issues related to the user.
• --repo owner/repository: Specifies the GitHub repository by the owner’s name and the repository’s name, where the issues should be queried.

Example Output:

RELEVANT ISSUES FOR YOU
Issues assigned to you: 3
OPEN: #145 Optimize search function, #150 Update dependencies, #153 Write tests
...

Reopen a Specific Issue

Code:

gh issue reopen issue_number

Motivation:

Occasionally, issues may be prematurely closed or require reopening due to further developments. This command provides a quick way to change an issue’s status back to open from the terminal.

Explanation:

• gh issue reopen: Reopens a closed issue in the repository.
• issue_number: The specific number of the issue to be reopened.

Example Output:

Reopened issue #125 - Performance improvements

Conclusion:

The gh issue command is a versatile tool for managing GitHub issues directly from the command line, providing streamlined access to view, create, list, and modify issues without leaving the terminal. By incorporating its functionality into your workflow, you can increase productivity and maintain focus on development tasks.