Skip to main content
This guide will walk you through deploying Gitflare on your Cloudflare account, creating your first repository, and performing your first Git operations.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js v22 or higher
  • pnpm v10.19.0 or higher
  • Cloudflare account (free tier works fine)
  • Git installed on your machine

​
Step 1: Set up your account

1

Clone the repository

Clone Gitflare to your local machine:
git clone https://github.com/mdhruvil/gitflare.git
cd gitflare
2

Install dependencies

Install all required dependencies using pnpm:
pnpm install
Gitflare uses pnpm workspaces to manage the monorepo structure.
3

Configure environment variables

Navigate to the web app directory and set up your environment:
cd apps/web
Create a .dev.vars file with the following:
SITE_URL=http://localhost:3000
For production deployment, you’ll also need to set these secrets in your Cloudflare dashboard or via wrangler.
4

Set up the database

Initialize the local D1 database:
pnpm db:migrate:local
This creates the SQLite database schema for users, repositories, and issues.
5

Start the development server

Launch the local development server:
pnpm dev
Open http://localhost:3000 in your browser. You should see the Gitflare homepage!
6

Create your account

Click Sign up and create your account with:
  • Username (this will be your repository owner name)
  • Email address
  • Password
Choose your username carefully - it will be part of all your repository URLs.

​
Step 2: Create your first repository

1

Navigate to the new repository page

After signing in, click New repository or navigate to the repositories page.
2

Configure your repository

Fill in the repository details:
{
  name: "my-first-repo",           // Letters, numbers, hyphens, underscores
  description: "My first Gitflare repository",
  isPrivate: false                  // Public or private
}
Repository names must:
  • Be 1-100 characters long
  • Contain only letters, numbers, hyphens, and underscores
  • Not end with .git
3

Create the repository

Click Create repository. Gitflare will:
  1. Create a new repository entry in the D1 database
  2. Initialize a new Durable Object for the repository
  3. Set up an empty bare Git repository
From the source code (apps/web/src/api/repos.ts:117-118):
const stub = getRepoDOStub(fullName);
await stub.ensureRepoInitialized();

​
Step 3: Perform your first Git operations

Now that your repository is created, let’s perform some Git operations!
1

Generate a personal access token

To push to your repository, you need a personal access token (PAT):
  1. Navigate to Settings > Personal Access Tokens
  2. Click Generate new token
  3. Give it a descriptive name like my-laptop
  4. Copy the token immediately (you won’t see it again!)
Store your PAT securely. Anyone with this token can push to your repositories.
2

Clone your repository

Clone your newly created repository:
git clone http://localhost:3000/username/my-first-repo.git
cd my-first-repo
For public repositories, you can clone without authentication. Private repositories require a PAT.
3

Add some content

Create a README file and make your first commit:
echo "# My First Repo" > README.md
git add README.md
git commit -m "Initial commit"
4

Push to Gitflare

Push your changes to Gitflare:
git push origin main
When prompted for credentials:
  • Username: Your Gitflare username
  • Password: Your personal access token
# Store credentials to avoid repeated prompts
git config credential.helper store
5

Verify in the web interface

Navigate to your repository in the web browser at:
http://localhost:3000/username/my-first-repo
You should see:
  • Your README.md file
  • The commit you just pushed
  • The repository tree structure

​
How it works

Here’s what happens during Git operations:
When you clone or pull from a Gitflare repository:
  1. Discovery: Git sends a request to /username/repo/info/refs?service=git-upload-pack
  2. Authentication: Gitflare verifies your credentials (from apps/web/src/lib/git-auth.ts:19-27):
    • Public repos: Allow anonymous read access
    • Private repos: Require valid PAT from repository owner
  3. Capability advertisement: Gitflare advertises supported Git capabilities
  4. Negotiation: Git client sends “want” and “have” refs to determine what objects to fetch
  5. Pack creation: Gitflare’s Durable Object collects the requested objects (from apps/web/src/git/service.ts:214-295)
  6. Transfer: Objects are packed and sent to the client
async collectObjectsForPack(wants: string[], haves: string[]): Promise<string[]> {
  const objectsToSend = new Set<string>();
  const visited = new Set<string>();
  const haveSet = new Set(haves);
  
  // BFS traversal of commit graph to collect all needed objects
  // ... traverses commits, trees, and blobs
  
  return Array.from(objectsToSend);
}
When you push to a Gitflare repository:
  1. Discovery: Git sends a request to /username/repo/info/refs?service=git-receive-pack
  2. Authentication: Gitflare verifies push permissions (from apps/web/src/lib/git-auth.ts:58-63):
    • Push operations always require authentication
    • Only the repository owner can push
  3. Pack reception: Git client sends a packfile with new objects
  4. Index pack: Gitflare indexes the packfile into the Durable Object storage (from apps/web/src/git/service.ts:204-212)
  5. Reference updates: Gitflare updates branch references (from apps/web/src/git/service.ts:599-738):
    • Validates old OID matches current reference
    • Ensures fast-forward updates (no force push)
    • Atomically updates all references
await git.indexPack({
  fs: this.fs,
  dir: this.gitdir,
  gitdir: this.gitdir,
  filepath: filePath,
  cache: this.cache,
});
Each repository in Gitflare has:
  • Durable Object: Stores the actual Git repository data
    • Git objects (blobs, trees, commits, tags)
    • References (branches, tags)
    • Packfiles
    • Virtualized file system on Durable Object SQLite
  • D1 Record: Stores metadata (from apps/web/src/api/repos.ts:103-120):
    • Repository name and description
    • Owner information
    • Public/private status
    • Creation timestamp
const result = await Repo.create({
  name: data.name,
  description: data.description.trim() || undefined,
  isPrivate: data.isPrivate,
  ownerId: user.id,
  owner: user.username,
});

​
Deploy to production

Ready to deploy Gitflare to production?
1

Create a Cloudflare account

If you haven’t already, sign up for a Cloudflare account.
2

Configure production environment

Set up your production environment variables via wrangler:
wrangler secret put SITE_URL
# Enter your production URL, e.g., https://git.yourdomain.com
3

Create production database

Create and migrate your production D1 database:
pnpm db:migrate:remote
4

Deploy to Cloudflare

Deploy your Gitflare instance:
cd apps/web
pnpm deploy
Your Gitflare instance will be live on Cloudflare Workers!

​
Next steps

Now that you have Gitflare running, explore more features:

Managing repositories

Learn about repository settings and access control

Git operations

Deep dive into all supported Git commands

Architecture

Understand how Gitflare works under the hood

Authentication

Set up authentication and personal access tokens

Build docs developers (and LLMs) love

Get started for freeTalk to us