{"record":{"id":"d280ae98c85fd391","repo":"facebook/docusaurus","slug":"you-cannot-deploy-from-this-branch-sourcebranch","errorCode":null,"errorMessage":"You cannot deploy from this branch (${sourceBranch}).\nYou will need to checkout to a different branch!","messagePattern":"You cannot deploy from this branch \\((.+?)\\)\\.\nYou will need to checkout to a different branch!","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/docusaurus/src/commands/deploy.ts","lineNumber":220,"sourceCode":"    deploymentRepoURL = buildHttpsUrl(\n      gitCredentials,\n      githubHost,\n      organizationName,\n      projectName,\n      githubPort,\n    );\n  }\n\n  logger.info`Remote repo URL: name=${obfuscateGitPass(deploymentRepoURL)}`;\n\n  // Check if this is a cross-repo publish.\n  const crossRepoPublish = !sourceRepoUrl.endsWith(\n    `${organizationName}/${projectName}.git`,\n  );\n\n  // We don't allow deploying to the same branch unless it's a cross publish.\n  if (sourceBranch === deploymentBranch && !crossRepoPublish) {\n    throw new Error(\n      `You cannot deploy from this branch (${sourceBranch}).` +\n        '\\nYou will need to checkout to a different branch!',\n    );\n  }\n\n  // Save the commit hash that triggers publish-gh-pages before checking\n  // out to deployment branch.\n  const currentCommit = exec('git rev-parse HEAD')?.stdout?.toString().trim();\n\n  const runDeploy = async (outputDirectory: string) => {\n    const targetDirectory = cliOptions.targetDir ?? '.';\n    const fromPath = outputDirectory;\n    const toPath = await fs.mkdtemp(\n      path.join(os.tmpdir(), `${projectName}-${deploymentBranch}`),\n    );\n    process.chdir(toPath);\n\n    // Clones the repo into the temp folder and checks out the target branch.","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus/src/commands/deploy.ts#L202-L238","documentation":"Thrown by `docusaurus deploy` when the branch you are currently on (`sourceBranch`) equals the deployment branch and this is not a cross-repo publish. Docusaurus refuses to push build output onto the branch it just built from, because that would overwrite the source tree. Cross-repo publishes (where the source repo differs from the deploy repo) are exempt.","triggerScenarios":"`sourceBranch === deploymentBranch` AND `sourceRepoUrl` still ends with `${organizationName}/${projectName}.git` (i.e. not a cross-repo deploy). Typical example: you are on `gh-pages` and try to deploy to `gh-pages`.","commonSituations":"Switched into the deployment branch by accident before running deploy; set `deploymentBranch` to your working branch; cloned and forgot to checkout `main`/`master` first; CI checked out the deploy branch.","solutions":["Checkout your source branch first: `git checkout main` (or `master`), then re-run `docusaurus deploy`.","If you intentionally deploy from a non-default branch, set `deploymentBranch` to a different value (e.g. `gh-pages`) so the two differ.","For a cross-repo setup, ensure the source repo URL does not match `${organizationName}/${projectName}.git` (use a separate deploy repo).","In CI, verify the checkout step pulls the source branch, not the deployment branch."],"exampleFix":"# before: on gh-pages, deploying to gh-pages\ngit branch # -> * gh-pages\ndocusaurus deploy  # throws\n# after\ngit checkout main\ndocusaurus deploy","handlingStrategy":"validation","validationCode":"import {execSync} from 'child_process';\nconst sourceBranch = execSync('git rev-parse --abbrev-ref HEAD').toString().trim();\nif (sourceBranch === deploymentBranch && !isCrossRepo) {\n  throw new Error(`Switch off ${sourceBranch} before deploying to it`);\n}","typeGuard":"function isSafeToDeploy(sourceBranch: string, deploymentBranch: string, crossRepo: boolean): boolean {\n  return crossRepo || sourceBranch !== deploymentBranch;\n}","tryCatchPattern":"try { await deploy(siteDir, cliOptions); }\ncatch (e) {\n  if (/cannot deploy from this branch/i.test(e.message)) {\n    console.error('Checkout your source branch first (e.g. git checkout main)'); process.exit(1);\n  }\n  throw e;\n}","preventionTips":["In CI, ensure the checkout step uses the source branch, not the deployment branch.","Name your deployment branch distinctly (`gh-pages`) so it never equals a source branch.","Add a pre-deploy git-branch assertion in the deploy script."],"tags":["deploy","github-pages","git","branch"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}