Skip to content
A GitHub Protocol & API emulation
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode improve code coverage Aug 9, 2018
repos moving git-server to prototypes (#157) Jun 8, 2018
test chore(lint): use latest eslint-config-airbnb-base Aug 20, 2019
.eslintrc.js chore(lint): use latest eslint-config-airbnb-base Aug 20, 2019
.npmignore build(.npmignore): re-add *.rest filter Aug 21, 2019
.releaserc.js chore(release): fix wrong release script Aug 20, 2019
.snyk fix: prototypes/git-server/.snyk & prototypes/git-server/package.json… Jul 2, 2018
.tidelift.yml chore(release): 1.0.0 [skip ci] Aug 20, 2019 increase test suite timeout Aug 19, 2019 chore(lint): use latest eslint-config-airbnb-base Aug 20, 2019
LICENSE.txt README cleanup Aug 20, 2019
config.js revert to info log level Aug 20, 2019
index.js [git-server] not possible to use w/o config.js #212 Jun 27, 2018
package-lock.json chore(release): fix wrong release script Aug 20, 2019
package.json chore(release): fix wrong release script Aug 20, 2019



codecov CircleCI GitHub license GitHub issues Greenkeeper badge LGTM Code Quality Grade: JavaScript


git-server serves a hierarchy of local Git repositories to Git clients accessing the repository over http:// and https:// protocol.

git-server expects the local Git repositories (either cloned or created with git init) to be organized as follows in the local file system:

├── <owner_1>/
│   └── <repo_1>
│   └── <repo_2>
├── <owner_2>/
│   └── <repo_1>
│   └── <repo_2>

Alternatively, a virtual repository mapping allows to 'mount' repositories independent of their location in the file system into a <owner>/<repo> hierarchy. A configuration example:

  virtualRepos: {
    owner1: {
      repo1: {
        path: './repo1',
    owner2: {
      repo2: {
        path: '/repos/repo2',

Repositories exposed via git-server can be used just like any repository hosted on GitHub, i.e. you can clone them and push changes to. The repository contents can be accessed with the same url patterns you would use to request files managed on GitHub.

The following protocols and APIs are currently supported:


cd <checkout dir>
npm install

Getting started

git-server is configured via the config.js file which is expected to exist in the current working directory. Here's the default configuration:

  appTitle: 'Helix Git Server',
  repoRoot: './repos',
  // repository mapping. allows to 'mount' repositories outside the 'repoRoot' structure.
  virtualRepos: {
    demoOwner: {
      demoRepo: {
        path: './virtual/example',
  listen: {
    http: {
      port: 5000,
      host: '',
    // https is optional
    https: {
      // cert: if no file is specfied a selfsigned certificate will be generated on-the-fly
      // cert: './localhost.crt',
      // key: if no file is specfied a key will be generated on-the-fly
      // key: './localhost.key',
      port: 5443,
      host: '',
  subdomainMapping: {
    // if enabled, <subdomain>.<baseDomain>/foo/bar/baz will be
    // resolved/mapped to<subdomain>/foo/bar/baz
    enable: true,
    baseDomains: [
      // some wildcarded DNS domains resolving to
  logs: {
    level: 'info', // fatal, error, warn, info, verbose, debug, trace
    logsDir: './logs',
    reqLogFormat: 'short', // used for morgan (request logging)

git-server uses helix-log for logging. The log level (fatal, error, warn, info, verbose, debug, trace) can be set via the logs.level property in the config (see above). For more information please refer to the helix-log project.

1. Create a local Git repository

cd ./repos
# create org
mkdir helix && cd helix
# initialize new git repo
mkdir test && cd test && git init
# allow to remotely push to this repo
git config receive.denyCurrentBranch updateInstead
# add a
echo '# test repo'>
git add . && git commit -m '1st commit'
cd ../../..

2. Start server

npm start

3. Fetch raw content of file in Git repo over http

curl http://localhost:5000/raw/helix/test/master/

Git Protocols and APIs

1. Git Raw Protocol

Serving content of a file in a git repo.

The requested file is specified by:

  • {owner}: GitHub organization or user
  • {repo}: repository name
  • {ref}: Git reference
    • branch name (e.g. master)
    • tag name (e.g. v1.0)
    • (full or shorthand) commit id (e.g. 7aeff3d)

GitHub URLs:


Local git-server URLs:

  • http://localhost:{port}/raw/{owner}/{repo}/{ref}/path/to/file
  • http://localhost:{port}/{owner}/{repo}/raw/{ref}/path/to/file
  •{port}/{owner}/{repo}/{ref}/path/to/file (using wildcarded DNS domain resolving to

Remote examples:


Local examples:

  • http://localhost:5000/adobe/project-helix/raw/master/
  • http://localhost:5000/raw/adobe/project-helix/master/ serves certain file types (e.g. JavaScript, CSS, HTML) with incorrect Content-Type: text/plain header. 3rd party solutions like address this issue. git-server serves files with correct content type.

2. Git HTTP Transfer Protocols

Support for git clone, push, fetch


git push support

The served local repo needs to be either a bare repo (git clone --bare or git init --bare) or the following option needs to be set:

git config receive.denyCurrentBranch updateInstead

more information

3. GitHub API v3

Documentation: GitHub API v3

GitHub Endpoint:

Local endpoint: http://localhost:{port}/api or e.g.{port} (using wildcarded DNS domain resolving to

Only a small subset of the GitHub API will be supported:

  • Get contents

    Note: The GitHub implementation supports files up to 1 megabyte in size.

  • Get blob

    Note: The GitHub implementation supports blobs up to 100 megabytes in size.

  • Get tree

  • Get commits

  • Get archive link

    Note: This method returns a 302 to a URL to download a tarball or zipball archive for a repository. git-server also supports an unofficial endpoint that is not rate limited and that doesn't redirect:


    Related issue/discussion: #5 Support

Local examples:

  • http://localhost:5000/api/repos/adobe/project-helix/contents/
  • http://localhost:5000/api/repos/adobe/project-helix/git/blobs/bf13fe66cbee379db6a3e4ebf0300b8bbc0f01b7

4. GitHub-like Web Server

(not yet implemented)



You can’t perform that action at this time.