# How code-server Handles GitHub Authentication via `--github-auth`

> Learn how code-server secures GitHub authentication using the GITHUB_TOKEN environment variable or config file not direct CLI arguments to prevent credential leaks.

- Repository: [Coder/code-server](https://github.com/coder/code-server)
- Tags: internals
- Published: 2026-03-01

---

**`code-server` strictly prohibits passing the `--github-auth` token as a direct CLI argument, instead requiring the `GITHUB_TOKEN` environment variable or a configuration file entry to prevent credential leakage in shell histories and process listings.**

The `coder/code-server` repository implements a defense-in-depth strategy for GitHub authentication tokens used to access services like the Open VSX marketplace. While the `--github-auth` option appears in the CLI help, the underlying TypeScript implementation in [`src/node/cli.ts`](https://github.com/coder/code-server/blob/main/src/node/cli.ts) enforces strict validation rules that reject unsafe input methods and automatically sanitize sensitive data from logs.

## Security-First Token Input Design

The `--github-auth` parameter is intentionally designed to prevent accidental exposure of personal access tokens. The system accepts credentials through only two secure channels, actively blocking the most common vector for secret leakage.

### Why Direct CLI Arguments Are Rejected

According to the source code in [`src/node/cli.ts`](https://github.com/coder/code-server/blob/main/src/node/cli.ts) (lines 407‑409), the `parse()` function inspects every incoming argument. If it detects `github-auth` arriving from the command line without an accompanying configuration file context, it immediately throws a fatal error:

```ts
if (key === "github-auth" && !opts?.configFile) {
  throw new Error("--github-auth can only be set in the config file or passed in via $GITHUB_TOKEN")
}

```

This validation ensures that tokens never appear in Bash history files (`~/.bash_history`), process listings (`ps aux`), or system logs where they could be harvested by malicious actors.

### Approved Authentication Methods

`code-server` accepts the GitHub token through these secure mechanisms:

- **The `GITHUB_TOKEN` environment variable** – Read once during startup, then purged from memory.
- **The `github-auth` configuration file entry** – Stored in YAML format at `~/.config/code-server/config.yaml` or a custom path specified via `--config`.

## Implementation Details in src/node/cli.ts

The authentication flow spans multiple stages of the CLI lifecycle, from argument parsing to secure cleanup.

### Option Definition (Lines 66‑68)

The `options` object declares the parameter with a descriptive warning embedded in the help text:

```ts
"github-auth": {
  type: "string",
  description: "GitHub authentication token (can only be passed in via $GITHUB_TOKEN or the config file).",
},

```

### Environment Variable Injection (Lines 630‑632)

After raw argument parsing completes, the CLI checks for the presence of `GITHUB_TOKEN` and maps it to the internal `github-auth` field:

```ts
if (process.env.GITHUB_TOKEN) {
  args["github-auth"] = process.env.GITHUB_TOKEN
}

```

### Secure Memory Cleanup (Lines 46‑48)

Immediately after ingestion, the code deletes the environment variable to prevent the token from propagating to child processes or appearing in crash dumps:

```ts
delete process.env.GITHUB_TOKEN

```

### Log Redaction (Lines 99‑100)

When generating debug output or configuration dumps, the CLI replaces the actual token with the literal string `<redacted>`:

```ts
"github-auth": args["github-auth"] ? "<redacted>" : undefined,

```

## Practical Configuration Examples

### Supplying a Token via Environment Variable

Export the token in your shell session before launching the server. The variable is consumed and removed automatically:

```bash
export GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXX
code-server

# Token is now stored internally; env var is deleted

```

### Providing a Token in a Config File

Create or edit the configuration file at the default location:

```yaml

# ~/.config/code-server/config.yaml

github-auth: ghp_XXXXXXXXXXXXXXXXXXXX
auth: password
password: your-secure-password

```

Launch with the config flag to satisfy the validation logic:

```bash
code-server --config ~/.config/code-server/config.yaml

```

### Attempting Direct CLI Usage (Will Fail)

The following command triggers the security exception defined in the validation block:

```bash
code-server --github-auth ghp_XXXXXXXXXXXXXXXXXXXX

# Error: --github-auth can only be set in the config file or passed in via $GITHUB_TOKEN

```

## Programmatic Token Access

For extension authors or integrators accessing the CLI internals, the token becomes available only after the `setDefaults()` function resolves environment variables and configuration files:

```ts
import { parse, setDefaults } from "code-server/src/node/cli"

const rawArgs = parse([])                     // Token not exposed here
const fullConfig = await setDefaults(rawArgs) // Token populated if GITHUB_TOKEN was set
const token = fullConfig["github-auth"]        // Use for Open VSX API calls

```

## Summary

- **CLI blocking**: The `parse()` function in [`src/node/cli.ts`](https://github.com/coder/code-server/blob/main/src/node/cli.ts) (lines 407‑409) explicitly throws an error if `--github-auth` appears as a direct command-line argument without a configuration file context.
- **Environment variable support**: The CLI reads `GITHUB_TOKEN` from `process.env` during startup (lines 630‑632) and assigns it to the internal `github-auth` field.
- **Memory sanitization**: The code immediately deletes `process.env.GITHUB_TOKEN` (lines 46‑48) to prevent leakage to subprocesses.
- **Log protection**: All diagnostic output redacts the token as `<redacted>` (lines 99‑100).
- **Dual input methods**: Tokens are accepted exclusively through environment variables or YAML configuration files.

## Frequently Asked Questions

### Why does code-server block the --github-auth flag on the command line?

Direct CLI arguments expose secrets in shell history files, process listings (`ps`), and system audit logs. By restricting input to environment variables and configuration files, `code-server` prevents tokens from persisting in plain text on the filesystem or appearing in terminal scrollback buffers.

### What happens to the GITHUB_TOKEN environment variable after code-server starts?

The application reads the value during initialization, stores it in the internal configuration object, and then immediately executes `delete process.env.GITHUB_TOKEN` (lines 46‑48). This removes the variable from the process environment, ensuring that child processes or crash reports cannot access the credential.

### Can I use both GITHUB_TOKEN and a config file simultaneously?

Yes. If both sources provide a token, the environment variable assignment at lines 630‑632 executes after configuration file parsing, meaning `GITHUB_TOKEN` effectively overrides the config file value. However, the validation logic (lines 407‑409) only enforces restrictions when a config file is *not* being used.

### How does code-server use the GitHub authentication token internally?

The token authenticates requests to the Open VSX marketplace and other GitHub services. When the application logs its configuration state or encounters errors, the redaction logic (lines 99‑100) ensures the token appears as `<redacted>` in all output, preventing accidental disclosure in log aggregation systems.