Skip to content

Commit

Permalink
Merge branch 'mh/doc-credential-helpers-with-pat' into seen
Browse files Browse the repository at this point in the history
Document that it is insecure to use Personal Access Tokens, which
some hosting providers take as username/password, embedded in URLs.

* mh/doc-credential-helpers-with-pat:
  docs: discuss caching personal access tokens
  docs: list popular credential helpers
  • Loading branch information
gitster committed Jan 14, 2025
2 parents ac35b5c + a90ff40 commit c5ac9dd
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 12 deletions.
17 changes: 17 additions & 0 deletions Documentation/git-credential-cache.txt
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,23 @@ variable (this example increases the cache time to 1 hour):
$ git config credential.helper 'cache --timeout=3600'
-------------------------------------------------------

PERSONAL ACCESS TOKENS
----------------------

Some remotes accept personal access tokens, which are randomly
generated and hard to memorise. They typically have a lifetime of weeks
or months.

git-credential-cache is inherently unsuitable for persistent storage of
personal access tokens. The credential will be forgotten after the cache
timeout. Even if you configure a long timeout, credentials will be
forgotten if the daemon dies.

To avoid frequently regenerating personal access tokens, configure a
credential helper with persistent storage. Alternatively, configure an
OAuth credential helper to generate credentials automatically. See
linkgit:gitcredentials[7], sections "Available helpers" and "OAuth".

GIT
---
Part of the linkgit:git[1] suite
41 changes: 29 additions & 12 deletions Documentation/gitcredentials.txt
Original file line number Diff line number Diff line change
Expand Up @@ -66,18 +66,7 @@ storage provided by the OS or other programs. Alternatively, a
credential-generating helper might generate credentials for certain servers via
some API.

To use a helper, you must first select one to use. Git currently
includes the following helpers:

cache::

Cache credentials in memory for a short period of time. See
linkgit:git-credential-cache[1] for details.

store::

Store credentials indefinitely on disk. See
linkgit:git-credential-store[1] for details.
To use a helper, you must first select one to use (see below for a list).

You may also have third-party helpers installed; search for
`credential-*` in the output of `git help -a`, and consult the
Expand Down Expand Up @@ -106,6 +95,28 @@ $ git config --global credential.helper foo

=== Available helpers

Git currently includes the following helpers:

cache::

Cache credentials in memory for a short period of time. See
linkgit:git-credential-cache[1] for details.

store::

Store credentials indefinitely on disk. See
linkgit:git-credential-store[1] for details.

Popular helpers with secure persistent storage include:

- git-credential-libsecret (Linux)

- git-credential-osxkeychain (macOS)

- git-credential-wincred (Windows)

- https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager] (cross platform, included in Git for Windows)

The community maintains a comprehensive list of Git credential helpers at
https://git-scm.com/doc/credential-helpers.

Expand All @@ -116,6 +127,12 @@ OAuth credential helper. Initial authentication opens a browser window to the
host. Subsequent authentication happens in the background. Many popular Git
hosts support OAuth.

Popular helpers with OAuth support include:

- https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager] (cross platform, included in Git for Windows)

- https://github.com/hickford/git-credential-oauth[git-credential-oauth] (cross platform, included in many Linux distributions)

CREDENTIAL CONTEXTS
-------------------

Expand Down

0 comments on commit c5ac9dd

Please sign in to comment.