Fork Sync & Branching Workflow

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• CONTRIBUTING.md
• ROADMAP.md
• .claude/rules/git-workflow.md
• .claude/rules/upstream-sync.md
• internal/cmd/deploy.go

This page documents the git management and release strategy for the dash-proxy fork of kamal-proxy. The project maintains a strict separation between upstream mirror tracking and internal development to ensure that custom certificate features (SAN batching and DNS-01 wildcards) can coexist with upstream fixes.

The workflow centers on the dash branch as the primary source of truth for the fork, while the main branch is reserved exclusively for tracking the basecamp repository. Upstream mergeability is not considered a design constraint; the project prioritizes features required for the dash gem.
Sources: CLAUDE.md:12-16, CLAUDE.md:65-71

Branching Strategy

The repository follows a specific branch map to manage different feature sets and upstream synchronization.

Core Branches

• dash: The main branch of the fork. All development work lands here, including certificate features and publishing workflows.
• main: A mirror of basecamp/kamal-proxy. It is used as a source for merging upstream fixes forward but is never a target for fork-specific commits.

Feature Branches

Specific features are maintained in dedicated branches before being merged into dash. The two primary certificate branches deliberately overlap in certain files (e.g., run.go, config.go, router.go) to feed both the SAN manager and the certificate registry.

Branch	Description	Conflict Surface vs dash
dash	Main development branch	N/A
main	Upstream mirror (Fast-forward only)	N/A
san-certificate-batching	SAN cert batching and ACME flags	run.go, config.go, router.go, go.mod
wildcard-certs	DNS-01 wildcard certs and registry	run.go, config.go, router.go, go.mod

Sources: CLAUDE.md:65-83

Workflow Diagram

The following diagram illustrates the relationship between upstream sources, the mirror, and the active development branch.

Upstream Synchronization

Synchronization occurs by fetching from the upstream remote and merging into dash. Upstream fixes are pulled forward via the main branch.

Synchronization Rules

1. Start of Sync: Every sync process begins with git fetch upstream --tags --prune.
2. No Commits on main: Commits are never allowed directly on the main branch to maintain a clean mirror.
3. Dependency Management: After merging main into certificate branches or dash, go mod tidy must be run to ensure the dependency graph correctly incorporates new upstream changes while retaining fork-specific libraries like lego.

Sources: CLAUDE.md:27-28, CLAUDE.md:38-39, CLAUDE.md:55

Release Workflow

Releases are managed via a specific script and naming convention to ensure compatibility with the kamal gem, which parses image tags as versions.

Versioning and Tagging

• Four-segment Tags: Versions must follow the vX.Y.Z.N format (e.g., v1.0.0.0).
• No Suffixes: Suffixes like -rc1 are prohibited because the Gem::Version comparison treats them as prereleases, which sorts them below the intended release.
• Single Tag Pushes: Developers must push one tag at a time (e.g., git push origin tag v1.0.0.0) rather than using git push --tags.

Release Execution

The process is executed using the script/release-dash tool, which performs the following steps:

1. Validates the tag grammar.
2. Runs the test suite (make test).
3. Creates the tag and pushes it to the origin.
4. Triggers CI (docker-publish.yml) to build multi-arch images (amd64+arm64).

Sources: CLAUDE.md:29-34, CLAUDE.md:35-37, CLAUDE.md:47-48

Critical Constraints

To maintain system integrity, several hard constraints must be followed regarding binary and module naming:

• Fixed Naming: The module, binary, RPC service, and socket names MUST remain kamal-proxy. The RPC name is registered in internal/server/commands.go and is dialed by multiple client sites; changing these names breaks the load-bearing infrastructure.
• Image Metadata: All published images must include the org.opencontainers.image.title=kamal-proxy label, as the kamal gem uses this to prune proxy images.
• No :latest Deploys: Deploys must point to specific versioned tags. Non-numeric tags crash the version check performed by the gem.

Sources: CLAUDE.md:23-26, CLAUDE.md:31-32, CLAUDE.md:90

Implementation Guide

When implementing new features to be merged into the workflow, the following anchors should be used for integration:

Component	File Path	Usage
Service Options	internal/server/service.go	Add per-service configuration knobs
CLI Flags	internal/cmd/deploy.go	Register new deployment flags
RPC Arguments	internal/server/commands.go	Define structs for client-server communication
Persistence	internal/server/service.go	Update MarshalJSON/UnmarshalJSON for state survival

Sources: ROADMAP.md:162-167

Contribution Process

The project uses GitHub discussions for feature requests and questions. Tasks are moved to the issue tracker only when they are actionable and well-understood. Issues tagged as "in progress" indicate active work, and contributors are encouraged to comment on issues before starting work to avoid duplication.
Sources: CONTRIBUTING.md:1-25