How to use the command "gh issue create" (with examples)

The “gh issue create” command is a part of the GitHub CLI tool that allows users to create GitHub issues on a repository directly from the command line. This command provides a convenient way to interactively create and manage issues without needing to switch to the GitHub website.

Use case 1: Create a new issue against the current repository interactively

Code:

gh issue create

Motivation: By running this command, users can create a new issue for the current repository in an interactive manner. This is useful when there is a need to quickly create an issue without specifying any additional parameters.

Explanation: The command “gh issue create” without any additional options allows the user to create a new issue interactively. It prompts the user for necessary information such as the issue title, body, and labels, and then creates the issue on the current repository.

Example output:

? Title: Fix broken link on homepage
? Body: The link to the blog page is not working properly. It redirects to a 404 page. Please fix it.
? Choose a label: (Use arrow keys)
❯ bug
  enhancement
  documentation
? Assignees: (Press <space> to select, <a> to toggle all, <i> to invert selection)
  user1
  user2
  user3
? Milestone: 1.0
? Ready to submit?: (y/N)

Use case 2: Create a new issue with the bug label interactively

Code:

gh issue create --label "bug"

Motivation: In situations where there is a need to create an issue with a specific label, using the “–label” option can save time by automatically assigning the desired label to the issue.

Explanation: The “–label” option is used to specify one or more labels for the new issue. In this example, the label “bug” is assigned to the issue being created.

Example output:

? Title: Broken link on homepage
? Body: The link to the blog page is not working properly. It redirects to a 404 page. Please fix it.
? Choose a label: bug
? Assignees: (Press <space> to select, <a> to toggle all, <i> to invert selection)
  user1
  user2
  user3
? Milestone: 1.0
? Ready to submit?: (y/N)

Use case 3: Create a new issue interactively and assign it to the specified users

Code:

gh issue create --assignee user1,user2,...

Motivation: Assigning issues to specific users can help in clearly assigning responsibility and ensuring that the issue is attended to by the appropriate individuals.

Explanation: The “–assignee” option is used to assign the issue to one or more specific users. By providing a comma-separated list of usernames, the issue is automatically assigned to the specified individuals.

Example output:

? Title: Page not loading
? Body: The page takes a long time to load. It seems to be related to the backend API call. Please investigate.
? Choose a label: (Use arrow keys)
  bug
❯ enhancement
  documentation
? Assignees: user1,user2,user3
? Milestone: 2.0
? Ready to submit?: (y/N)

Use case 4: Create a new issue with a title, body, and assign it to the current user

Code:

gh issue create --title "title" --body "body" --assignee "@me"

Motivation: By combining multiple options, users can create issues with specific attributes quickly. In this example, the issue is assigned to the current user.

Explanation: The “–title” option is used to specify the title of the issue. The “–body” option is used to provide the body text for the issue. The “–assignee” option with the value “@me” assigns the issue to the currently authenticated user.

Example output:

? Title: Important issue
? Body: We have identified a critical security vulnerability in the system. Urgent attention required.
? Choose a label: (Use arrow keys)
❯ bug
  enhancement
  documentation
? Assignees: user1
? Milestone: 3.0
? Ready to submit?: (y/N)

Use case 5: Create a new issue interactively, reading the body text from a file

Code:

gh issue create --body-file path/to/file

Motivation: For lengthy or complex issue descriptions, it can be more convenient to write the body text in a file and use the “–body-file” option to read the content from the file.

Explanation: The “–body-file” option is used to specify the path to a file containing the body text for the issue. This allows the user to enter the issue details in a separate file, making it easier to manage and modify the content.

Example output:

? Title: New feature proposal
? Body (file): path/to/file
? Choose a label: enhancement
? Assignees: user1,user2
? Milestone: 4.0
? Ready to submit?: (y/N)

Use case 6: Create a new issue in the default web browser

Code:

gh issue create --web

Motivation: Some users may prefer to create issues using the GitHub web interface. By using the “–web” option, the command opens the default web browser with a pre-filled issue creation form.

Explanation: The “–web” option opens the GitHub website with the issue creation form pre-filled. This allows users who are more familiar with the web interface to create issues using a familiar environment.

Example output:

Opening https://github.com/repo-name/issues/new?title=Sample%20issue&body=Sample%20body

Use case 7: Display the help

Code:

gh issue create --help

Motivation: When first using a command, or when in need of a refresher on the available options, the “–help” option provides access to the command’s help documentation.

Explanation: The “–help” option displays the help documentation for the “gh issue create” command. It provides information on all available options and how to use them effectively.

Example output:

usage: gh issue create [<id>] [--add-assignee <assignee>...] [--assignee <assignee>...] [--body-file <path>] [--label <label>...] [--milestone <milestone>] [--project <project>] [--state <state>] [--title <title>] [--web] [flags]

Create a new issue

Flags:
      --add-assignee=[]           User to add as assignee. Use "@" with usernames to assign by username instead of by search.
      --assignee=[]               User(s) to assign to (use "@" with usernames to assign by username instead of by search)
      --body-file=FILE             Read body text from FILE
      --label=[]                   Add labels
      --milestone=""               Milestone to add the issue to
      --project=""                 Project to add the issue to
      --state=""                   Set the issue state (default: the default state of a new issue on the repository)
      --title=""                   Title of the issue
      --web                        Open the browser to create an issue

Global Flags:
  -R, --repo REPO      Select another repository using the OWNER/REPO format
  -h, --help           Show help for command

Conclusion:

The “gh issue create” command is a versatile tool that enables users to create GitHub issues directly from the command line. By providing options for interactivity, user assignments, labels, and more, it offers a convenient and efficient way to manage and track issues without the need to switch between different tools or interfaces. Whether creating a simple issue or a complex issue with multiple parameters, the “gh issue create” command offers flexibility and ease of use.