> ## 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.

# Authenticate GitHits in CI and headless environments

> Authenticate GitHits in CI pipelines, SSH sessions, and containers with an API token, tunneled OAuth, or file storage.

CI environments, SSH sessions, and containers may not be able to open a browser for OAuth. Use an API token for automation. For an interactive SSH session, print the sign-in URL and forward the local callback port from the browser machine.

## Option 1: API token (recommended for CI)

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.

<Steps>
  <Step title="Get your API token">
    Open [your token settings](https://app.githits.com/settings/tokens) to create an API token. Copy your API token — it starts with `ghi-`.
  </Step>

  <Step title="Set the environment variable">
    Export the token in your shell or add it to your CI configuration as a secret:

    ```bash theme={null}
    export GITHITS_API_TOKEN=ghi-your-token-here
    ```
  </Step>

  <Step title="Verify authentication">
    Confirm that GitHits picks up the token:

    ```bash theme={null}
    npx githits@latest auth status
    ```

    The output should show you as authenticated and indicate that credentials are sourced from the environment variable.
  </Step>
</Steps>

### GitHub Actions example

Add your API token as a repository secret named `GITHITS_API_TOKEN`, then reference it in your workflow:

```yaml theme={null}
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - 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.

### Group requests by run

With CLI 0.25.1 or later, set [`GITHITS_SESSION_ID`](/cli/environment-variables#githits_session_id) before starting commands to group requests from one CI or agent run. Use an opaque value of 1–64 ASCII letters, digits, underscores, or hyphens, such as `ci_run-42_agent-a`. Keep the value consistent for related commands and choose a new value for a separate run. GitHits sends explicit values unchanged; leave it unset for automatic detection.

## Option 2: OAuth over an SSH tunnel

If the CLI runs on a remote host but your browser runs locally, choose a fixed callback port on the remote host:

```bash Remote host theme={null}
npx githits@latest login --no-browser --port 8765
```

From the browser machine, forward the same port to the remote loopback listener:

```bash Browser machine theme={null}
ssh -N -L 8765:127.0.0.1:8765 user@remote-host
```

Keep the tunnel open, then open the sign-in URL printed by the remote CLI. Replace `user@remote-host` with your SSH destination.

## 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:

```bash theme={null}
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.

<Warning>
  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.
</Warning>

You can also set file storage permanently in your config:

```toml theme={null}
# macOS/Linux: ~/.config/githits/config.toml
# Windows: %APPDATA%\githits\config.toml
[auth]
storage = "file"
```

## Choosing the right approach

| Scenario | Recommended approach |
| - | - |
| GitHub Actions, GitLab CI, CircleCI | `GITHITS_API_TOKEN` secret |
| SSH session with local browser available | `login --no-browser --port <port>` plus an SSH tunnel |
| Long-running container, no browser | `GITHITS_API_TOKEN` |
| Local scripted workflow, trusted machine | File storage OAuth |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.