---
title: "Securing Heroku CLI Credentials with System Keychain Storage"
description: "Heroku CLI 11.8.0 changes credential storage by making the system keychain the default and retaining .netrc as a fallback. The transition began in 11.6.0, when the CLI stored tokens in both locations to preserve existing workflows. The credential manager uses macOS security, Linux Secret Service through secret-tool, or Windows PasswordVault, storing credentials under “heroku-cli” with the account email as the identifier. Authentication lookup prioritizes HEROKU_API_KEY, then HEROKU_NETRC_WRITE, keychain storage, and .netrc files; unsupported or failing keychain access falls back to .netrc. Version 11.8.0 also adds a Git credential helper, so commands such as git push heroku main continue without configuration changes, while CI/CD can keep using HEROKU_API_KEY and Linux users may need secret-tool."
---

# Securing Heroku CLI Credentials with System Keychain Storage

[Heroku](https://yomu.fyi/company/heroku) · Katy Bowman · Jul 1, 2026

**Type:** Announcement

## Summary

Heroku CLI 11.8.0 changes credential storage by making the system keychain the default and retaining .netrc as a fallback. The transition began in 11.6.0, when the CLI stored tokens in both locations to preserve existing workflows. The credential manager uses macOS security, Linux Secret Service through secret-tool, or Windows PasswordVault, storing credentials under “heroku-cli” with the account email as the identifier. Authentication lookup prioritizes HEROKU\_API\_KEY, then HEROKU\_NETRC\_WRITE, keychain storage, and .netrc files; unsupported or failing keychain access falls back to .netrc. Version 11.8.0 also adds a Git credential helper, so commands such as git push heroku main continue without configuration changes, while CI/CD can keep using HEROKU\_API\_KEY and Linux users may need secret-tool.

## Context

The Heroku CLI is improving authentication security by moving credentials from default .netrc storage to operating-system keychains while preserving existing Git, API, CI/CD, and custom .netrc-based workflows.

## Approach / What changed

The CLI adds a credential manager that uses native secure-storage tools on macOS, Linux, and Windows, defines a four-tier credential lookup order, retains .netrc fallback and forced storage through HEROKU\_NETRC\_WRITE=true, and configures a Git credential helper for repositories.

## Takeaways

- Version 11.8.0 makes system keychain storage the default; .netrc remains available when keychain support is unavailable, fails, or is explicitly selected.
- Credential lookup checks HEROKU\_API\_KEY first, followed by HEROKU\_NETRC\_WRITE, system keychain storage, and finally .netrc files.
- The CLI configures a Git credential helper so git push heroku main continues working without workflow changes; Linux users may need the secret-tool package.

**Tags:** [Authentication](https://yomu.fyi/topic/authentication), [Heroku](https://yomu.fyi/topic/heroku), [Security](https://yomu.fyi/topic/security)

- Source: [Heroku](https://www.heroku.com/blog/securing-heroku-cli-credentials-with-system-keychain-storage)
- Source URL: https://www.heroku.com/blog/securing-heroku-cli-credentials-with-system-keychain-storage
- Ingested by Yomu: 2026-09-10T04:05:31.644Z

[Read original post](https://www.heroku.com/blog/securing-heroku-cli-credentials-with-system-keychain-storage)