Understanding the .config/gh/hosts.yml File
The .config/gh/hosts.yml file serves as the central repository for authentication metadata used by the GitHub CLI, commonly referred to by its command-name gh. This configuration file is responsible for storing the state of user sessions across different GitHub environments, including the public cloud and private GitHub Enterprise Server instances. On most Linux and macOS systems, the file is located within the user's home directory at ~/.config/gh/hosts.yml, while on Windows, it is typically found in the %AppData%\gh\ directory.
The internal structure of the file follows the YAML serialization standard. It organizes data by hostname, where each host entry contains specific keys such as user, oauth_token, and git_protocol. The oauth_token is a sensitive authentication token that allows the gh tool to perform actions on behalf of the user via the GitHub API. The git_protocol entry determines whether the CLI should use SSH or HTTPS when performing git operations like cloning or pushing. Because this file contains plain-text credentials, it is highly recommended to ensure that file permissions are restricted to the owner only.
While users can manually edit this file, it is primarily managed through the gh auth suite of commands. For instance, running gh auth login will automatically update the hosts.yml file with a new OAuth session. For further reading on managing credentials and host configurations, consult the Official GitHub CLI Manual.