What causes "GITHUB_TOKEN environment variable is required" in remix-run/react-router?

Export a valid GitHub personal access token before running the script: GITHUB_TOKEN=ghp_xxx (or `export GITHUB_TOKEN=ghp_xxx` then run).

remix-run/react-router · critical · Error

GITHUB_TOKEN environment variable is required

Error message

GITHUB_TOKEN environment variable is required

What it means

This is a custom guard error thrown by getToken() in scripts/utils/github.ts before any GitHub API request is dispatched. The scripts/utils/github.ts module wraps @octokit/request to talk to the remix-run/react-router repo, and every requestOptions() call embeds an authorization header built from getToken(). Without a token, the Octokit request would either fail with a 401 at the API boundary or hit rate limits, so the script fails fast with this explicit message instead.

Source

Thrown at scripts/utils/github.ts:11

import { request } from "@octokit/request";

import { getGitTag } from "./packages.ts";

const OWNER = "remix-run";
const REPO = "react-router";

function getToken(): string {
  let token = process.env.GITHUB_TOKEN;
  if (!token) {
    throw new Error("GITHUB_TOKEN environment variable is required");
  }
  return token;
}

function requestOptions() {
  return {
    owner: OWNER,
    repo: REPO,
    headers: { authorization: `token ${getToken()}` },
  };
}

export type CreateReleaseResult =
  | { status: "created"; url: string }
  | { status: "skipped"; reason: string }
  | { status: "error"; error: string };

/**

View on GitHub (pinned to 1fd704a7da)

Solutions

Export a valid GitHub personal access token before running the script: GITHUB_TOKEN=ghp_xxx <script> (or `export GITHUB_TOKEN=ghp_xxx` then run).
If using a devkey registry per repo conventions, add GITHUB_TOKEN to dev-setup/config/devkey/registry.kdl and run the script via `devkey run github-token -- <cmd>` so the grant is injected.
In CI, ensure the job has `env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}` (or a PAT secret) on the step or job.
Verify the token is visible to the process with a one-off check that reads process.env.GITHUB_TOKEN by NAME (never print the value) — e.g. assert it is non-empty before invoking the script.

Example fix

// before
$ pnpm tsx scripts/some-release-script.ts
Error: GITHUB_TOKEN environment variable is required

// after (one-off)
$ export GITHUB_TOKEN=$(devkey need github-token)
$ pnpm tsx scripts/some-release-script.ts

// after (CI step)
- name: Run release script
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: pnpm tsx scripts/some-release-script.ts

Defensive patterns

Strategy: validation

Validate before calling

// Run before invoking any script that imports scripts/utils/github.ts
function assertGithubToken(): void {
  if (!process.env.GITHUB_TOKEN) {
    throw new Error(
      "GITHUB_TOKEN is missing. Set it via `export GITHUB_TOKEN=$(devkey need github-token)` " +
        "or map `secrets.GITHUB_TOKEN` to env in CI."
    );
  }
}
assertGithubToken();

Type guard

// Environment guards narrow on presence, not type (always string|undefined).
const hasGithubToken = (): boolean =>
  typeof process.env.GITHUB_TOKEN === "string" && process.env.GITHUB_TOKEN.length > 0;

Try / catch

// Catch only to emit a friendlier message, then re-throw — never swallow.
try {
  await runReleaseScript();
} catch (err) {
  if (err instanceof Error && err.message.includes("GITHUB_TOKEN")) {
    console.error(
      "Missing GITHUB_TOKEN. Create a PAT at https://github.com/settings/tokens " +
        "with `repo` scope and export it before re-running."
    );
    process.exit(1);
  }
  throw err; // unrelated error — preserve stack
}

Prevention

Add a preflight env check at the top of every release/tag script that imports github.ts so the failure is reported before any network work begins.
Document the required env var in the script's JSDoc and in AGENTS.md so contributors know to set it before the first run.
In CI, fail the job fast with a dedicated `Check env` step rather than letting the script fail mid-request.
Use the repo's devkey registry for local runs so the token is never copy-pasted into shell history.
Never log the token value — verify presence by length/non-emptiness, not by printing.

When it happens

Trigger: Running any release/tag/PR script that imports scripts/utils/github.ts (which calls getGitTag from packages.ts and then requestOptions()) without GITHUB_TOKEN exported in the environment. Concretely: invoking scripts that call getToken() -> requestOptions() -> @octokit/request for repo data, releases, or tags while process.env.GITHUB_TOKEN is undefined or empty.

Common situations: Running release scripts locally without sourcing the .env that defines GITHUB_TOKEN; CI (GitHub Actions) where the secret was not mapped to the GITHUB_TOKEN env var on the job; token set in a different shell session than the one running the script; typo in the variable name (e.g. GH_TOKEN vs GITHUB_TOKEN); the script being invoked through a subshell or tman run that does not inherit the parent environment.

Related errors

AI-assisted analysis of remix-run/react-router@1fd704a7da (2026-08-12). Data as JSON: /api/errors/d8b122af940a0200. Report an issue: GitHub.