Please set the GIT_USER environment variable, or explicitly

Error message

Please set the GIT_USER environment variable, or explicitly specify USE_SSH instead!

What it means

Thrown by deploy when neither GIT_USER nor USE_SSH=true is set and the source remote URL is not SSH-protocol (so SSH cannot be inferred). Docusaurus needs one of these to push the build to the gh-pages branch: HTTPS deploys require GIT_USER, SSH deploys require USE_SSH=true or an SSH remote URL.

Source

Thrown at packages/docusaurus/src/commands/deploy.ts:128

    exec('git rev-parse --abbrev-ref HEAD', {
      log: false,
      failfast: true,
    })
      ?.stdout?.toString()
      .trim();

  const gitUser = process.env.GIT_USER;

  let useSSH =
    process.env.USE_SSH !== undefined &&
    process.env.USE_SSH.toLowerCase() === 'true';

  if (!gitUser && !useSSH) {
    // If USE_SSH is unspecified: try inferring from repo URL
    if (process.env.USE_SSH === undefined && hasSSHProtocol(sourceRepoUrl)) {
      useSSH = true;
    } else {
      throw new Error(
        'Please set the GIT_USER environment variable, or explicitly specify USE_SSH instead!',
      );
    }
  }

  const organizationName =
    process.env.ORGANIZATION_NAME ??
    process.env.CIRCLE_PROJECT_USERNAME ??
    siteConfig.organizationName;
  if (!organizationName) {
    throw new Error(
      `Missing project organization name. Did you forget to define "organizationName" in ${siteConfigPath}? You may also export it via the ORGANIZATION_NAME environment variable.`,
    );
  }
  logger.info`organizationName: name=${organizationName}`;

  const projectName =
    process.env.PROJECT_NAME ??

View on GitHub (pinned to 3f483e80e3)

Solutions

For HTTPS: `export GIT_USER=<your-github-username>` then re-run.
For SSH: `export USE_SSH=true` (or rely on an SSH origin remote with USE_SSH unset).
In GitHub Actions, set GIT_USER (often `${{ github.actor }}`) in the deploy step env.
Avoid setting USE_SSH=false explicitly if you want SSH inference from the remote URL.

Example fix

# before
docusaurus deploy  # HTTPS origin, no GIT_USER, no USE_SSH
# after
export GIT_USER=octocat
docusaurus deploy

Defensive patterns

Strategy: validation

Validate before calling

const hasGitUser = Boolean(process.env.GIT_USER);
const useSSH = process.env.USE_SSH?.toLowerCase() === 'true';
if (!hasGitUser && !useSSH) {
  throw new Error('Set GIT_USER or USE_SSH=true before deploying.');
}

Prevention

Always export GIT_USER (or USE_SSH=true) in your deploy environment.
In GitHub Actions, set GIT_USER to `${{ github.actor }}`.
Do not set USE_SSH=false explicitly if you want SSH inference from the remote URL.

When it happens

Trigger: Running deploy with an HTTPS origin remote, GIT_USER unset, and USE_SSH unset/false. The inference fallback only triggers when USE_SSH is undefined AND the remote URL already uses SSH; otherwise this error fires.

Common situations: First-time deploy setup, CI (GitHub Actions) where GIT_USER is not exported, or accidentally setting USE_SSH=false explicitly instead of leaving it unset for inference.

Related errors

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/a634d3aeaf50a5aa. Report an issue: GitHub.