Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.githits.com/llms.txt

Use this file to discover all available pages before exploring further.

CI environments, SSH sessions, and containers cannot open a browser for OAuth. GitHits gives you two practical options: authenticate with an API token (recommended for CI) or use the --no-browser flag to get a URL you can open on another device. An API token lets you authenticate without any browser interaction. The token is read from an environment variable, so you can inject it as a CI secret without modifying your code or config files.
1

Get your API token

Log in to githits.com and navigate to your account settings. Copy your API token — it starts with ghi-.
2

Set the environment variable

Export the token in your shell or add it to your CI configuration as a secret:
export GITHITS_API_TOKEN=ghi-your-token-here
3

Verify authentication

Confirm that GitHits picks up the token:
npx githits@latest auth status
The output should show you as authenticated and indicate that credentials are sourced from the environment variable.

​
GitHub Actions example

Add your API token as a repository secret named GITHITS_API_TOKEN, then reference it in your workflow: 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'

      - name: Run GitHits
        env:
          GITHITS_API_TOKEN: ${{ secrets.GITHITS_API_TOKEN }}
        run: |
          npx githits@latest auth status
The same pattern works for GitLab CI (variables:), CircleCI (project environment variables), and any other CI system that supports injecting secrets as environment variables.

​
Option 2: Browser-less OAuth

If you need OAuth authentication but cannot open a browser on the same machine, use --no-browser. GitHits prints a URL instead of launching a browser — open it on any device to complete authentication. 
npx githits@latest login --no-browser
This is useful for SSH sessions where you have a browser available on your local machine but not on the remote host.

​
Option 3: File storage OAuth (scripted environments)

If you need OAuth credentials persisted for a scripted environment that runs repeatedly, you can store them in a file instead of the system keychain: 
GITHITS_AUTH_STORAGE=file npx githits@latest login --force
Subsequent runs in that environment read credentials from the file without any browser or keychain interaction.
File storage is not encrypted. The OAuth credentials are written as plain JSON files under your GitHits config directory. Any process that can read files as your OS user can read the tokens. For CI and automation, prefer GITHITS_API_TOKEN — it is easier to rotate and does not leave unencrypted credential files on disk.
You can also set file storage permanently in your config: 
# macOS/Linux: ~/.config/githits/config.toml
# Windows: %APPDATA%\githits\config.toml
[auth]
storage = "file"

​
Choosing the right approach

ScenarioRecommended approach
GitHub Actions, GitLab CI, CircleCIGITHITS_API_TOKEN secret
SSH session with local browser availablenpx githits@latest login --no-browser
Long-running container, no browserGITHITS_API_TOKEN
Local scripted workflow, trusted machineFile storage OAuth