Securing Heroku CLI Credentials with System Keychain Storage

Beginning in version 11.8.0, we will be improving the security of the Heroku CLI by storing authentication credentials in your system keychain by default. The Heroku credential manager makes use of OS-native secure storage tools with interfaces designed for sensitive data while maintaining compatibility with existing developer workflows.

We began the transition to our new credential management tool in version 11.6.0 of the CLI, storing the token in both the keychain and the .netrc file to ensure this improvement is as seamless as possible. With version 11.8.0, managing credentials via the system keychain becomes the default, while the use of .netrc files becomes a fallback.

Your next heroku login will automatically use keychain storage and commands like git push heroku main will continue working without configuration changes. The CLI also maintains backward compatibility through a four-tier credential lookup: the HEROKU_API_KEY environment variable takes precedence, then the HEROKU_NETRC_WRITE environment variable, followed by keychain storage, and finally .netrc files.

Secure credential storage leveraging native system tools

Your Heroku credentials will now live alongside your other sensitive data in the secure storage your operating system already provides.

• macOS: The CLI uses the security command to interact with Keychain Access.
• Linux: The CLI accesses credentials on GNOME-based Linux distributions through the Secret Service API via secret-tool, which works with common backends like GNOME Keyring or KWallet.
• Windows: The CLI stores credentials using the PasswordVault API, integrating with Windows Credential Manager.

In all cases, credentials are stored under the service name “heroku-cli” with your Heroku account email as the account identifier, making them easy to locate and manage through each platform’s native credential viewer.

Maintaining netrc support

Netrc support remains a first-class feature for compatibility with existing toolchains. The .netrc file format has been a cross-tool credential standard for decades, used by cURL, Wget, Git, and other utilities. Heroku’s original CLI design used this format to enable seamless workflows like git push heroku main and authenticated API calls via cURL.

The credential manager preserves these workflows, both through configuring custom integrations and allowing for the option to continue using .netrc files for credential management. Systems without a supported keychain application will automatically fall back to storing credentials in .netrc files. Otherwise, setting the environment variable HEROKU_NETRC_WRITE=true when running heroku login will force the credential manager to store the token in the .netrc file instead of the credential manager.

If you had previously set HEROKU_NETRC_WRITE=true and then unset it in order to enable the credential manager to use your system keychain or if you had never set it in the first place, your credentials will remain in your .netrc file. The credential manager will not automatically remove them, though your token will expire after the designated time period. You may remove them by running HEROKU_NETRC_WRITE=true heroku logout or manually editing the .netrc file to remove credentials that are no longer needed.

Git integration

Since its inception, Heroku has used Git as the primary method for deploying Heroku applications. The command git push heroku main has become synonymous with the ease Heroku offers for managing deployment and hosting. Version 11.8.0 of the CLI includes a new git credential helper to ensure that your git workflow remains unchanged.

From a day-to-day perspective, your git workflow will not change. When you log in with heroku login, set up your git remote using heroku git:remote, or create a new app with heroku apps:create the CLI will automatically configure the credential helper for your repository. Additionally, in order to ease the transition, for a limited amount of time any CLI command run will also configure the credential helper if it hasn’t already been set up.

Developer experience

How credentials are read

The new credential manager uses a four-tier lookup precedence:

1. The HEROKU_API_KEY environment variable takes top precedence. As always, if it is set, it takes priority over all other authentication methods.
2. The HEROKU_NETRC_WRITE environment variable will force the use of the .netrc for storage, lookup, or removal when set to true.
3. The system keychain takes precedence if the HEROKU_API_KEY or HEROKU_NETRC_WRITE environment variables are not set.
4. Finally, the .netrc file is used if a supported system keychain is not available or if it fails for any reason.

Getting started with the credential manager

For most developers no action is required. After your CLI updates to version 11.8.0, the next time you run heroku login, your credentials will automatically be stored in your system keychain instead of the .netrc file. You won’t notice any workflow changes, just the benefit of more secure credential storage using your operating system’s native tools.

For CI/CD environments, the existing automation will remain unchanged. The HEROKU_API_KEY environment variable will continue to work exactly as it has for years. The CLI’s credential lookup precedence ensures that environment variables take priority over keychain storage, so your build scripts, deployment pipelines, and automated workflows require no modifications. If the HEROKU_API_KEY has not been set, the credential manager will use the precedence order detailed above, most likely falling back to using the .netrc file for headless Linux environments.

For Linux users, you may need to install the secret-tool package if it’s not already installed in your system to enable Secret Service integration. If keychain access isn’t available, the CLI will automatically fall back to using the .netrc file.

For developers with custom netrc integrations, existing scripts and tools that read credentials from the .netrc file continue to function during the transition. Scripts using curl –netrc or other utilities that rely on the .netrc file will remain compatible until the Heroku token stored there expires. If specific tooling requires continuing to store your token in a .netrc file, you can set the HEROKU_NETRC_WRITE=true environment variable to maintain the use of the .netrc file.

A more secure Heroku CLI

System keychain integration brings modern credential security to the Heroku CLI while preserving the interoperability and workflows developers rely on. Upgrade today or visit the installation guide. For a full list of updates, check out the CLI changelog. As always, we welcome your feedback as we continue to improve the developer experience.