Deploy to GitHub without git config --global

[eric-hc]

Somewhat of a discussion in #1771, but I was wondering if anyone has been able to deploy to gh-pages without setting a global git config. I am trying this, but have not had any luck yet.

export GIT_USER={...}
git config user.name {...}
git config user.email {...}

I am even setting {user}:{key} for the GIT_USER environment variable, and tried setting them in a .gitconfig file, but the deploy script still wants global git config.

[Advait251206]

Yes — you can deploy Docusaurus to GitHub Pages without using git config --global, but you need to understand what the deploy script actually depends on.

The key point is:

The deployment fails not because Docusaurus requires global config, but because git commit requires a valid local identity.

---

❌ Why your current approach fails

You tried:

export GIT_USER=...
git config user.name ...
git config user.email ...

But Docusaurus’ deploy script ultimately runs:

git commit

And Git requires one of these to be set in the current repo context:

• local repo config (.git/config)
• OR global config (~/.gitconfig)

If neither is properly set, Git throws an error.

---

✅ Correct solution (NO global config needed)

✔ Option 1 — set local git config (best practice)

Run this inside your repo:

git config user.name "Your Name"
git config user.email "you@example.com"

This writes to:

./.git/config

✔ No global config required
✔ Works in CI
✔ Safe and isolated

---

✔ Option 2 — inline config during deploy (CI-friendly)

You can bypass both global + manual config using:

git -c user.name="Your Name" \
    -c user.email="you@example.com" \
    commit -m "deploy"

But Docusaurus deploy script doesn’t expose this directly, so this is mainly for custom scripts.

---

✔ Option 3 — use environment variables correctly

Docusaurus expects:

GIT_USER=your-username

BUT:

👉 This only affects authentication (push access), NOT commit identity.

So you still must set:

git config user.name
git config user.email

locally or in CI.

---

⚠️ Important misunderstanding

This part:

GIT_USER={user}:{key}

❌ Incorrect.

GIT_USER is ONLY the GitHub username.

Authentication is handled via:

• GH_TOKEN
• or SSH key
• or HTTPS token in CI

---

🚀 Best CI/CD setup (no global config anywhere)

Example GitHub Actions:

- name: Configure Git
  run: |
    git config user.name "github-actions[bot]"
    git config user.email "github-actions[bot]@users.noreply.github.com"

- name: Deploy
  run: npm run deploy
  env:
    GIT_USER: github-actions[bot]
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

✔ no global config
✔ fully isolated
✔ recommended approach

---

🧠 Why Docusaurus behaves this way

The deploy script internally uses:

• execa / git CLI
• assumes Git is already configured
• does NOT manage identity automatically

So responsibility is on the environment.

---

✅ Summary

You cannot avoid Git identity configuration entirely, but you CAN avoid global config:

Method	Works?
git config --global	❌ not required
git config user.* (local)	✅ best
CI git config	✅ best for automation
only GIT_USER	❌ not enough

---

🚀 Final answer

👉 You don’t need global git config
👉 But you MUST set local repo identity or CI identity

---

If this answer helped or pointed you in the right direction, I'd appreciate it if you could mark it as the accepted answer so it's easier for others with the same issue to find.

Also, if you found my contribution useful, I'd appreciate it if you could check out my GitHub profile, follow me, and star any repositories you find interesting.

GitHub: https://github.com/Advait251206