Git Smart HTTP Protocol

Overview

gitGost implements the Git Smart HTTP protocol as defined in the Git documentation. This protocol enables Git clients to communicate with the gitGost service using standard git push and git fetch commands over HTTP/HTTPS. The Smart HTTP protocol consists of two main phases:

Discovery Phase - Client discovers available references and capabilities
Data Transfer Phase - Client sends or receives packfiles

Protocol Flow

Push Operation (git push)

Fetch Operation (git fetch/pull)

PKT-Line Format

The Git Smart HTTP protocol uses the pkt-line format for all communication. Each line is prefixed with a 4-character hexadecimal length.

Format Specification

Length Prefix: 4 hex digits (includes the 4 bytes itself)
Data: Variable length payload
Flush Packet: 0000 - indicates end of section

Examples

0032git-upload-pack /project.git\0host=example.com\0

Breakdown:

0032 = 50 bytes total (0x32 = 50)
Payload is 46 bytes

Flush packet (end of section)

Implementation

gitGost implements pkt-line parsing and writing:

// Write a pkt-line
func WritePktLine(w io.Writer, data string) error {
    if data == "" {
        _, err := w.Write([]byte("0000"))
        return err
    }
    length := len(data) + 4
    _, err := fmt.Fprintf(w, "%04x%s", length, data)
    return err
}

Source: internal/http/handlers.go:46-55

Capabilities

gitGost advertises the following capabilities during the discovery phase:

Receive-Pack (Push) Capabilities

capability

Server will send detailed status about ref updates

capability

Client can delete remote references

capability

Multiplexed progress, error, and data on a single connection

capability

Suppress server-side progress messages

capability

Server understands offset deltas in packfiles

capability

Client can send push options (e.g., pr-hash=abc123)

Implementation: See internal/http/handlers.go:100

Side-Band-64k Protocol

The side-band-64k protocol allows the server to send three types of messages to the client:

Side-Band Format

Each side-band message follows this structure:

<length><band><message>

length: 4-byte hex length (includes band byte and message)
band: 1-byte band identifier (0x01, 0x02, or 0x03)
message: Variable-length data

Example Implementation

func WriteSidebandLine(w io.Writer, band byte, message string) error {
    if message == "" {
        return nil
    }
    if !strings.HasSuffix(message, "\n") {
        message += "\n"
    }
    
    data := append([]byte{band}, []byte(message)...)
    length := len(data) + 4
    
    fmt.Fprintf(w, "%04x", length)
    w.Write(data)
    return nil
}

Source: internal/http/handlers.go:58-77

Authentication

gitGost requires no authentication for push operations to maintain complete anonymity. The service authenticates with GitHub on behalf of the user using its own bot account.

The anonymous nature of gitGost means:

No username/password required from users
No SSH keys needed
No GitHub tokens from contributors
Complete metadata anonymization

Protocol Endpoints

The Git Smart HTTP protocol is implemented through specific endpoints:

Discovery: GET /v1/gh/:owner/:repo/info/refs?service=<service>
Data Transfer: POST /v1/gh/:owner/:repo/<service>

See individual endpoint documentation:

Push Options

gitGost supports custom push options for advanced workflows: Push options are parsed during the packfile extraction phase:

if strings.HasPrefix(lineStr, "push-option=pr-hash=") {
    prHash = strings.TrimPrefix(lineStr, "push-option=pr-hash=")
    prHash = strings.TrimRight(prHash, "\n")
}

Source: internal/git/receive.go:86-90

Security & Rate Limiting

gitGost implements multiple layers of protection:

Per-IP Rate Limiting

Limit: 5 PRs per hour per IP address
Window: 1 hour sliding window
Response: HTTP 200 with error in side-band channel

Global Burst Detection

Monitors: Push attempts across all IPs
Threshold: 20 pushes from 10+ IPs in 60 seconds
Action: Admin notification via ntfy

Panic Mode

When activated, all push operations are rejected:

remote: SERVICE TEMPORARILY SUSPENDED
remote: The panic button has been activated.
remote: Please try again in 15 minutes.

Content-Type Headers

Git Smart HTTP uses specific Content-Type headers:

Discovery Phase

Content-Type

application/x-git-receive-pack-advertisement

Content-Type

application/x-git-upload-pack-advertisement

Data Transfer Phase

Content-Type

application/x-git-receive-pack-request

Content-Type

application/x-git-receive-pack-result

Content-Type

application/x-git-upload-pack-request

Content-Type

application/x-git-upload-pack-result

Receive-Pack API

POST endpoint for pushing commits

Upload-Pack API

POST endpoint for fetching commits

Git Protocol Docs

Official Git Smart HTTP specification

Quickstart Guide

Get started with gitGost in 2 minutes

Git Protocol

Anonymous Operations

Public Endpoints

Admin

Git Smart HTTP Protocol

Overview

Protocol Flow

Push Operation (git push)

Fetch Operation (git fetch/pull)

PKT-Line Format

Format Specification

Examples

Implementation

Capabilities

Receive-Pack (Push) Capabilities

Side-Band-64k Protocol

Side-Band Format

Example Implementation

Authentication

Protocol Endpoints

Push Options

Security & Rate Limiting

Per-IP Rate Limiting

Global Burst Detection

Panic Mode

Content-Type Headers

Discovery Phase

Data Transfer Phase

Receive-Pack API

Upload-Pack API

Git Protocol Docs

Quickstart Guide

​Overview

​Protocol Flow

​Push Operation (git push)

​Fetch Operation (git fetch/pull)

​PKT-Line Format

​Format Specification

​Examples

​Implementation

​Capabilities

​Receive-Pack (Push) Capabilities

​Side-Band-64k Protocol

​Side-Band Format

​Example Implementation

​Authentication

​Protocol Endpoints

​Push Options

​Security & Rate Limiting

​Per-IP Rate Limiting

​Global Burst Detection

​Panic Mode

​Content-Type Headers

​Discovery Phase

​Data Transfer Phase

​Related Resources

Receive-Pack API

Upload-Pack API

Git Protocol Docs

Quickstart Guide

Overview

Protocol Flow

Push Operation (git push)

Fetch Operation (git fetch/pull)

PKT-Line Format

Format Specification

Examples

Implementation

Capabilities

Receive-Pack (Push) Capabilities

Side-Band-64k Protocol

Side-Band Format

Example Implementation

Authentication

Protocol Endpoints

Push Options

Security & Rate Limiting

Per-IP Rate Limiting

Global Burst Detection

Panic Mode

Content-Type Headers

Discovery Phase

Data Transfer Phase

Related Resources