Overview

Last week, the GitHub Issues & Project team introduced public preview of 🔍 API support for advanced issue search for GitHub.com, which gives GitHub users the ability to build more complex issue search queries.

Introducing this to GitHub CLI users and automation affects multiple gh commands that allow users to search for issues:

• gh search issues
• gh issues list --search

Few important notes:

1. This is only applicable to issues; advanced pull request search is not currently supported.

2. This is currently available to GitHub Free / Team / Enterprise Cloud accounts but not available to GitHub Enterprise Cloud with Data Residency or GitHub Enterprise Server yet

3. Becoming the default on September 4th 2025, flags should be avoided as they will error when removed when moving to generally available (GA).

Acceptance Criteria

Controlling public preview

1. When a user views configuration settings with gh config
   Then advanced_issue_search is presented

   $ gh config
   Display or change configuration settings for gh.
   
   Current respected settings:
   
   - `git_protocol`: the protocol to use for git clone and push operations {https|ssh} (default https)
   - `editor`: the text editor program to use for authoring text
   - `prompt`: toggle interactive prompting in the terminal {enabled|disabled} (default enabled)
   - `prefer_editor_prompt`: toggle preference for editor-based interactive prompting in the terminal {enabled|disabled} (default disabled)
   - `pager`: the terminal pager program to send standard output to
   - `http_unix_socket`: the path to a Unix socket through which to make an HTTP connection
   - `browser`: the web browser to use for opening URLs
   - `advanced_issue_search`: toggle advanced issue search API public preview {enabled|disabled} (default disabled) 

2. Given a user has neither enabled or disabled advanced issue search
   When a user lists current configuration settings with gh config list
   Then advanced_issue_search shows as disabled and the existing standard issue search is used

3. When a user opts in to advanced issue search with gh config set advanced_issue_search enabled
   Then gh config list shows the new setting enabled and the new advanced issue search is used if available

4. When a user specifies GH_ADVANCED_ISSUE_SEARCH as a truthy value (anything other than 0, false, no, or empty string)
   Then the new advanced issue search is used if available

gh issue list --search

1. Given a user has disabled advanced issue search preview
   And Given the user is authenticated to github.com
   When the user searches for issues using gh issue list --search ...
   Then the existing issue type is specified in the search query

2. Given a user has enabled advanced issue search preview
   And Given the user is authenticated to github.com
   When the user searches for issues using gh issue list --search ...
   Then the advanced issue type is specified in the search query

3. Given a user has enabled advanced issue search preview
   And Given the user is authenticated to ghe.com
   When the user searches for issues using gh issue list --search ...
   Then the existing issue type is specified in the search query

4. Given a user has enabled advanced issue search preview
   And Given the user is authenticated to GitHub Enterprise Server
   When the user searches for issues using gh issue list --search ...
   Then the existing issue type is specified in the search query

gh search issue

1. Given a user has disabled advanced issue search preview
   And Given the user is authenticated to github.com
   When the user searches for issues using gh search issue
   Then the existing issue type is specified in the search query

2. Given a user has enabled advanced issue search preview
   And Given the user is authenticated to github.com
   When the user searches for issues using gh search issue
   Then the advanced issue type is specified in the search query

3. Given a user has enabled advanced issue search preview
   And Given the user is authenticated to ghe.com
   When the user searches for issues using gh search issue
   Then the existing issue type is specified in the search query

4. Given a user has enabled advanced issue search preview
   And Given the user is authenticated to GitHub Enterprise Server
   When the user searches for issues using gh search issue
   Then the existing issue type is specified in the search query

Notes

• For information on how gh detects available features, see featuredetection package and Discovering the GraphQL API docs