Running "git push" command failed. Does the GitHub user acco

Error message

Running "git push" command failed. Does the GitHub user account you are using have push access to the repository?

What it means

Thrown after `git push --force origin <deploymentBranch>` returns a non-zero exit code. The push itself failed for a git/transport/permission reason; Docusaurus surfaces this as a hint that the authenticated user probably lacks push rights to the deployment repository.

Source

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

    if (gitUserName) {
      exec(`git config user.name ${escapeArg(gitUserName)}`, {failfast: true});
    }

    const gitUserEmail = process.env.GIT_USER_EMAIL;
    if (gitUserEmail) {
      exec(`git config user.email ${escapeArg(gitUserEmail)}`, {
        failfast: true,
      });
    }

    const commitMessage =
      process.env.CUSTOM_COMMIT_MESSAGE ??
      `Deploy website - based on ${currentCommit}`;
    const commitResults = exec(
      `git commit -m ${escapeArg(commitMessage)} --allow-empty`,
    );
    if (exec(`git push --force origin ${deploymentBranch}`).exitCode !== 0) {
      throw new Error(
        'Running "git push" command failed. Does the GitHub user account you are using have push access to the repository?',
      );
    } else if (commitResults.exitCode === 0) {
      // The commit might return a non-zero value when site is up to date.
      let websiteURL;
      if (githubHost === 'github.com') {
        websiteURL = projectName.includes('.github.io')
          ? `https://${organizationName}.github.io/`
          : `https://${organizationName}.github.io/${projectName}/`;
      } else {
        // GitHub enterprise hosting.
        websiteURL = `https://${githubHost}/pages/${organizationName}/${projectName}/`;
      }
      exec(`echo "Website is live at ${websiteURL}."`, {failfast: true});
      process.exit(0);
    }
  };

View on GitHub (pinned to 3f483e80e3)

Solutions

Verify the deploy identity has push access: for SSH, `ssh -T git@github.com`; for HTTPS, regenerate the PAT with `repo` scope and set `GIT_USER` + use the token flow.
Check `git remote -v` on the deployment repo and confirm the URL points to a repo you can write to.
Disable or relax branch protection on the deployment branch (e.g. `gh-pages`), or push to an unprotected branch.
Re-run `docusaurus deploy` with the correct credentials; inspect the git output above the error for the real upstream message.

Example fix

# before: HTTPS deploy with expired token
GIT_USER=olduser docusaurus deploy  # push fails
# after
gh auth token | read TOKEN
GIT_USER=currentUser GH_TOKEN=$TOKEN docusaurus deploy

Defensive patterns

Strategy: retry

Validate before calling

import {execSync} from 'child_process';
// pre-flight: can we even reach/write the remote?
try { execSync('git ls-remote --exit-code origin', {stdio: 'ignore'}); }
catch { throw new Error('No push access to origin — fix credentials before deploy'); }

Try / catch

for (let attempt = 1; attempt <= 3; attempt++) {
  try { await deploy(siteDir, cliOptions); break; }
  catch (e) {
    if (/git push/.test(e.message) && attempt < 3) { await sleep(2000); continue; }
    throw e;
  }
}

Prevention

Use a long-lived deploy token (or SSH key) stored in CI secrets, not a personal account.
Disable branch protection on the deployment branch or grant bypass to the deploy identity.
Verify `git remote -v` points to a writable repo before deploy.

When it happens

Trigger: `git push --force origin <deploymentBranch>` exits non-zero during the deploy step, e.g. bad credentials, no write access, branch protection rules, wrong SSH key, or an incorrect remote URL.

Common situations: Wrong `GIT_USER`; expired GitHub token; SSH key not added; deploy branch is protected (e.g. requires PR); using HTTPS deploy with a revoked PAT; cross-repo deploy where the user has no push permission on the target repo.

Related errors

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