Practice Now
git
git archive
error resolution
protocol issues
troubleshooting

git archive fatal Operation not supported by protocol

Interview Questions practice on Codemia

Over 8,000 real interview questions from top companies, searchable by company and role.

Browse interview questions
Git & Version ControlDebugging & Errors

Introduction

The error fatal: Operation not supported by protocol when running git archive --remote occurs because the remote server does not support the archive protocol over that connection type. GitHub, GitLab.com, and most hosted Git services disable git archive --remote for security and performance reasons. The fix depends on your situation: clone the repo and archive locally, use the hosting platform's API to download archives, or switch to a protocol that supports the operation.

The Error

bash
1git archive --remote=[email protected]:user/repo.git HEAD | tar -x
2# fatal: Operation not supported by protocol
3
4git archive --remote=https://github.com/user/repo.git HEAD -o repo.tar.gz
5# fatal: Operation not supported by protocol

git archive --remote asks the remote server to create and send an archive. The server must support this operation, and many do not.

Why It Fails

git archive --remote uses the Git upload-archive protocol. The server must have git-upload-archive enabled. Many hosting providers disable this because:

  • Security: It allows unauthenticated access to repository contents
  • Performance: Creating archives server-side is CPU-intensive
  • Abuse prevention: Prevents using servers as file download CDNs

Platform Support

Platformgit archive --remoteAlternative
GitHubNot supportedGitHub API / web download
GitLab.comNot supportedGitLab API
Self-hosted GitLabSupported (configurable)Direct or API
Bitbucket CloudNot supportedBitbucket API
Self-hosted Git serverUsually supportedDepends on config
Gitea / GogsSupportedAPI also available

Fix 1: Clone and Archive Locally

bash
1# Clone the repository
2git clone --depth 1 [email protected]:user/repo.git
3cd repo
4
5# Create archive from local repo
6git archive --format=tar.gz --output=../repo.tar.gz HEAD
7
8# Or archive a specific path
9git archive HEAD:src/ --format=tar.gz --output=../src.tar.gz
10
11# Shallow clone + archive (minimal download)
12git clone --depth 1 --branch v2.0 [email protected]:user/repo.git temp-repo
13cd temp-repo
14git archive HEAD --format=zip --output=../release-v2.0.zip
15cd .. && rm -rf temp-repo

Fix 2: GitHub API / Web Download

bash
1# Download a tarball via GitHub API
2curl -L -o repo.tar.gz https://api.github.com/repos/user/repo/tarball/main
3
4# Download a zipball
5curl -L -o repo.zip https://api.github.com/repos/user/repo/zipball/main
6
7# Download a specific tag
8curl -L -o v2.0.tar.gz https://api.github.com/repos/user/repo/tarball/v2.0
9
10# Using gh CLI (handles authentication)
11gh api repos/user/repo/tarball/main > repo.tar.gz
12
13# Direct download URL (public repos)
14curl -L -o repo.tar.gz https://github.com/user/repo/archive/refs/heads/main.tar.gz
15curl -L -o repo.tar.gz https://github.com/user/repo/archive/refs/tags/v2.0.tar.gz

Fix 3: GitLab API

bash
1# GitLab archive download
2curl --header "PRIVATE-TOKEN: your-token" \
3  "https://gitlab.com/api/v4/projects/PROJECT_ID/repository/archive.tar.gz?sha=main" \
4  -o repo.tar.gz
5
6# By project path (URL-encoded)
7curl --header "PRIVATE-TOKEN: your-token" \
8  "https://gitlab.com/api/v4/projects/user%2Frepo/repository/archive.zip" \
9  -o repo.zip

Fix 4: Enable on Self-Hosted Git Server

If you control the Git server, enable git-upload-archive:

bash
1# In the bare repository on the server
2cd /path/to/repo.git
3git config uploadarchive.allowUnreachable true
4
5# Or in the global Git config
6git config --global daemon.uploadarch true

For Gitolite:

perl
1# In gitolite.conf
2repo my-repo
3    R = @all
4    option upload-archive = 1

For self-hosted GitLab:

ruby
# In gitlab.rb
gitlab_rails['gitlab_shell_upload_archive'] = true

Fix 5: Use SSH Protocol with Upload-Archive

Some servers support archive over SSH but not over HTTPS:

bash
1# Try SSH protocol explicitly
2git archive --remote=ssh://[email protected]/path/to/repo.git HEAD --format=tar.gz > repo.tar.gz
3
4# With a specific branch or tag
5git archive --remote=ssh://[email protected]/path/to/repo.git v2.0 --format=zip > release.zip
6
7# Archive a specific subdirectory
8git archive --remote=ssh://[email protected]/path/to/repo.git HEAD:src/ > src.tar

CI/CD Pipeline Usage

yaml
1# GitHub Actions — download archive instead of git archive --remote
2jobs:
3  build:
4    runs-on: ubuntu-latest
5    steps:
6      - uses: actions/checkout@v4
7      # Now archive locally
8      - run: git archive --format=tar.gz HEAD -o release.tar.gz
9
10# GitLab CI — git archive works because the repo is already cloned
11build:
12  script:
13    - git archive --format=tar.gz HEAD -o release.tar.gz
14  artifacts:
15    paths:
16      - release.tar.gz

git archive Options

bash
1# Common local git archive usage
2git archive HEAD --format=tar.gz --output=project.tar.gz
3
4# Specific branch
5git archive main --format=zip --output=main.zip
6
7# Specific tag
8git archive v2.0 --format=tar.gz --prefix=myproject-2.0/ -o release.tar.gz
9
10# Specific directory
11git archive HEAD:docs/ --format=tar --output=docs.tar
12
13# With prefix (all files under a directory in the archive)
14git archive --prefix=myproject/ HEAD | gzip > myproject.tar.gz
15
16# Exclude files using export-ignore
17# Add to .gitattributes:
18# tests/ export-ignore
19# .github/ export-ignore
20git archive HEAD --format=tar.gz -o release.tar.gz

Common Pitfalls

  • Assuming --remote works everywhere: Most hosted Git services do not support git archive --remote. Always have a fallback plan (clone + archive locally, or use the platform API).
  • Forgetting authentication for private repos: API downloads for private repos require tokens. Use gh api (GitHub CLI) or curl with authentication headers.
  • Large repositories: git archive does not support --depth. If you only need an archive and want to minimize download, use git clone --depth 1 then archive locally.
  • Missing --format flag: Without --format, git archive defaults to tar. For gzip, use --format=tar.gz or pipe through gzip: git archive HEAD | gzip > repo.tar.gz.
  • .gitattributes export-ignore: Files with export-ignore in .gitattributes are excluded from git archive output. This can cause confusion if expected files are missing from the archive.

Summary

  • git archive --remote fails on GitHub, GitLab.com, and most hosted services
  • Clone the repo with --depth 1 and archive locally as the simplest workaround
  • Use platform APIs (curl GitHub/GitLab URLs) for direct archive downloads
  • Self-hosted servers can enable upload-archive in Git or server configuration
  • In CI/CD, the repo is already cloned — use git archive HEAD locally
Related reading
Free course
Beginner
7 lessons
2 hours
Tackling System Design Interview Problems

A short course that equips you with the skills to approach system design interviews methodically.

Start the free course
Track what you have practised

A free account saves your progress, solutions and study plan across every problem on Codemia.

Interview Questions practice on Codemia

Over 8,000 real interview questions from top companies, searchable by company and role.

Browse interview questions
Codemia
© 2026 Codemia
Resources
Legal
Social
All Rights Reserved.