facebook/docusaurus · error

For GitHub pages organization deployments, 'docusaurus deplo

Error message

For GitHub pages organization deployments, 'docusaurus deploy' does not assume anymore that 'master' is your default Git branch.
Please provide the branch name to deploy to as an environment variable, for example DEPLOYMENT_BRANCH=main or DEPLOYMENT_BRANCH=master .
You can also set the deploymentBranch property in docusaurus.config.js .

What it means

Thrown when deploying a GitHub Pages *organization* site (repo name contains `.github.io`) but no deployment branch has been specified. Docusaurus no longer assumes `master` for org pages; the user must explicitly state where to push. The deploy command checks `DEPLOYMENT_BRANCH` env var and `siteConfig.deploymentBranch`; if both are absent for an org-pages repo, it refuses to guess.

Source

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

    exec('echo "Skipping deploy on a pull request."', {
      log: false,
      failfast: true,
    });
    process.exit(0);
  }

  // github.io indicates organization repos that deploy via default branch. All
  // others use gh-pages (either case can be configured actually, but we can
  // make educated guesses). Organization deploys look like:
  // - Git repo: https://github.com/<organization>/<organization>.github.io
  // - Site url: https://<organization>.github.io
  const isGitHubPagesOrganizationDeploy = projectName.includes('.github.io');
  if (
    isGitHubPagesOrganizationDeploy &&
    !process.env.DEPLOYMENT_BRANCH &&
    !siteConfig.deploymentBranch
  ) {
    throw new Error(`For GitHub pages organization deployments, 'docusaurus deploy' does not assume anymore that 'master' is your default Git branch.
Please provide the branch name to deploy to as an environment variable, for example DEPLOYMENT_BRANCH=main or DEPLOYMENT_BRANCH=master .
You can also set the deploymentBranch property in docusaurus.config.js .`);
  }

  const deploymentBranch =
    process.env.DEPLOYMENT_BRANCH ?? siteConfig.deploymentBranch ?? 'gh-pages';
  logger.info`deploymentBranch: name=${deploymentBranch}`;

  const githubHost =
    process.env.GITHUB_HOST ?? siteConfig.githubHost ?? 'github.com';
  const githubPort = process.env.GITHUB_PORT ?? siteConfig.githubPort;

  let deploymentRepoURL: string;
  if (useSSH) {
    deploymentRepoURL = buildSshUrl(
      githubHost,
      organizationName,
      projectName,

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Set `deploymentBranch: 'main'` (or your org-pages default branch) in `docusaurus.config.js`.
2. Export `DEPLOYMENT_BRANCH=main` (or `master`) in your deploy environment.
3. Confirm the actual default branch on GitHub (`https://github.com/<org>/<org>.github.io`) and match it.
4. If this is a project site (not an org site), rename the repo so it does not end in `.github.io` to fall back to the `gh-pages` default.

Example fix

// before
export default {
  organizationName: 'my-org',
  projectName: 'my-org.github.io',
};
// after
export default {
  organizationName: 'my-org',
  projectName: 'my-org.github.io',
  deploymentBranch: 'main',
};

const isOrgPages = projectName.includes('.github.io');
const hasBranch = Boolean(process.env.DEPLOYMENT_BRANCH || siteConfig.deploymentBranch);
if (isOrgPages && !hasBranch) {
  throw new Error('Set deploymentBranch for an org .github.io site');
}

function isOrgPagesDeploy(projectName: string): boolean {
  return typeof projectName === 'string' && projectName.includes('.github.io');
}

try { await deploy(siteDir, cliOptions); }
catch (e) {
  if (/does not assume anymore that 'master'/.test(e.message)) {
    process.env.DEPLOYMENT_BRANCH = 'main'; // or set in config
    await deploy(siteDir, cliOptions);
  } else throw e;
}

When it happens

Trigger: `projectName` resolves to a value containing `.github.io` (e.g. `my-org.github.io`) AND neither `process.env.DEPLOYMENT_BRANCH` nor `siteConfig.deploymentBranch` is set.

Common situations: Migrating an org/user `.github.io` site from an older Docusaurus that assumed `master`; first deploy after GitHub renamed the default branch to `main`; new org site that never set `deploymentBranch`.

Related errors

• Missing project organization name. Did you forget to define
• Missing project name. Did you forget to define "projectName"
• Please set the GIT_USER environment variable, or explicitly
• You cannot deploy from this branch (${sourceBranch}). You wi
• Unknown Docusaurus VCS preset name: ${process.env.DOCUSAURUS

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