---
description: Configure ghtkn as a Git credential helper and switch GitHub Apps by repository owner. Use when setting up git authentication via ghtkn, handling fork repos, or troubleshooting the credential helper on macOS.
---

# Git Credential Helper

`version >= v0.1.2`

You can use ghtkn as a [Git Credential Helper](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage):

```sh
git config --global credential.helper '!ghtkn git-credential'
```

```ini
[credential]
	helper =
	helper = !ghtkn git-credential
```

> [!IMPORTANT]
> `helper =` is necessary to disable other helpers.
> https://git-scm.com/docs/gitcredentials#_configuration_options
> > If credential.helper is configured to the empty string, this resets the helper list to empty
> > (so you may override a helper set by a lower-priority config file by configuring the empty-string helper, followed by whatever set of helpers you would like).

Beyond convenience, the credential helper is the safest way to use ghtkn with git: git invokes `ghtkn git-credential` itself for each operation, so you never run `ghtkn get` and the token never reaches your shell output or a script variable you might print. This is the recommended pattern for automation and coding agents, which have leaked tokens by printing what `ghtkn get` returned (see [Token Management](token-management.md)). Note this covers git only; `gh` does not use git credential helpers, so run it with [`ghtkn exec`](exec.md) (`ghtkn exec -e GH_TOKEN -- gh ...`) instead.

## Switching GitHub Apps by repository owner

If you want to switch GitHub Apps by repository owner,

1. Set `.apps[].git_owner` or `.apps[].git_owners` in a configuration file
1. Configure Git `git config credential.useHttpPath true`

```sh
git config --global credential.useHttpPath true
```

```yaml
apps:
  - name: suzuki-shunsuke/write
    client_id: xxx
    git_owner: suzuki-shunsuke # Using this app if the repository owner is suzuki-shunsuke
```

One app can also cover several repository owners. This is what you want for a GitHub App owned by an enterprise and installed on several organizations: `client_id` must be unique across apps, so the app can't be repeated once per owner. List the owners in `git_owners` instead:

```yaml
apps:
  - name: my-company
    client_id: xxx
    git_owners: # Using this app if the repository owner is one of these
      - my-company
      - my-company-sandbox
```

`git_owner` and `git_owners` are mutually exclusive; set one or the other in an app.

> [!WARNING]
> A repository owner must be unique across apps, whether it's set in `git_owner` or in `git_owners`.
> Please assign a repository owner (organization and user) to only one app.
> For instance, if you use a read-only app and a write app for a repository owner and you want to push commits, you should assign the owner to the write app.
>
> ```yaml
> apps:
>   - name: suzuki-shunsuke/write
>     client_id: xxx
>     git_owner: suzuki-shunsuke # Using this app if the repository owner is suzuki-shunsuke
>   - name: suzuki-shunsuke/read-only
>     client_id: xxx
>     # git_owner: suzuki-shunsuke # Don't set `git_owner` to read-only app to push commits
> ```

### Switching GitHub Apps to access fork repositories

Unfortunately, `.apps[].git_owner` and `.apps[].git_owners` don't match when accessing fork repositories.
For instance, when you checkout a pull request from a fork repository by [gh pr checkout](https://cli.github.com/manual/gh_pr_checkout) command and push commits to the fork repository, they don't work unless you configure fork repositories in `ghtkn.yaml`.

As of ghtkn v0.2.6, the environment variable `GHTKN_GIT_APP` is useful.
`GHTKN_GIT_APP` is similar to `GHTKN_APP` (see [Using Multiple Apps](multiple-apps.md)) but it's used for Git Credential Helper.

e.g.

```sh
export GHTKN_GIT_APP=suzuki-shunsuke/git
```

The priority of the app used for Git Credential Helper is as follows:

1. `.apps[].git_owner` or `.apps[].git_owners` if it matches the repository owner in the credential path (this requires `credential.useHttpPath true`)
1. `GHTKN_GIT_APP`
1. `GHTKN_APP` if `GHTKN_GIT_APP` is not set
1. The default app

## :warning: Troubleshooting of Git Credential Helper on macOS

If Git Credential Helper doesn't work on macOS, please check if osxkeychain is used.

You can check the trace log of Git by `GIT_TRACE=1 GIT_CURL_VERBOSE=1`.

```sh
GIT_TRACE=1 GIT_CURL_VERBOSE=1 git push origin
```

If git outputs the following log, Git uses `git-credential-osxkeychain`, not ghtkn.

```
09:25:49.373133 git.c:750               trace: exec: git-credential-osxkeychain get
09:25:49.373152 run-command.c:655       trace: run_command: git-credential-osxkeychain get
```

Please check the git config.

```sh
git config --get-all --show-origin credential.helper
```

The following output shows osxkeychain is used by the system setting `/Library/Developer/CommandLineTools/usr/share/git-core/gitconfig`.

```
file:/Library/Developer/CommandLineTools/usr/share/git-core/gitconfig   osxkeychain
file:/Users/shunsukesuzuki/.gitconfig   !ghtkn git-credential
```

To solve the problem, please set credential.helper to the empty string.

```ini
[credential]
	helper =
	helper = !ghtkn git-credential
```

https://git-scm.com/docs/gitcredentials#_configuration_options

> If credential.helper is configured to the empty string, this resets the helper list to empty
> (so you may override a helper set by a lower-priority config file by configuring the empty-string helper, followed by whatever set of helpers you would like).