Generic Sync

Code Storage can keep a repository in sync with a named Git host that uses HTTPS authentication. Your tools, automations, and users still use the Code Storage remote. Use Generic Sync when you want to:

Mirror a repository from GitLab, Bitbucket, Gitea, Forgejo, Codeberg, or SourceHut
Push to Code Storage and let Code Storage forward those writes to the upstream host
Continue to use Code Storage APIs, JWT-backed remotes, ephemeral branches, and webhooks on the mirrored repository

Sync modes

Code Storage currently supports three Git Sync modes:

Mode	Best for	Authentication
GitHub App	Private GitHub repositories and webhook-driven sync	GitHub App installation token
Public GitHub	Public GitHub repositories you want to pull from without credentials	No GitHub credentials
Generic HTTPS Git	GitLab, Bitbucket, Gitea, Forgejo, Codeberg, SourceHut, and similar hosts	Stored username/password or token

This page covers Generic HTTPS Git. For GitHub, see GitHub Sync.

Supported providers

Generic Git Sync supports named providers that authenticate over HTTPS with a username and password, or with a token:

gitlab
bitbucket
gitea
forgejo
codeberg
sr.ht or sourcehut

For some providers, Code Storage can derive the public upstream host automatically:

gitlab -> gitlab.com
bitbucket -> bitbucket.org
codeberg -> codeberg.org
sr.ht -> git.sr.ht

Set upstream_host for each self-hosted provider. Also set it for providers with no fixed public host, such as gitea and forgejo. Generic HTTPS Git sync does not support Git LFS.

Generic Git setup

Generic provider setup happens in three steps:

Create the Code Storage repository with a generic Git base.
Store the HTTPS credential for that repository.
Start the initial pull.

1. Create the synced repository

This example creates a Code Storage repository with GitLab as its base. For a self-hosted GitLab instance, include upstreamHost / upstream_host.

const repo = await store.createRepo({
  id: 'my-gitlab-repo',
  baseRepo: {
    provider: 'gitlab',
    owner: 'your-group',
    name: 'your-repo',
    defaultBranch: 'main',
  },
  defaultBranch: 'main',
});

repo = await storage.create_repo(
    id="my-gitlab-repo",
    base_repo={
        "provider": "gitlab",
        "owner": "your-group",
        "name": "your-repo",
        "default_branch": "main",
    },
    default_branch="main",
)

repo, err := client.CreateRepo(context.Background(), storage.CreateRepoOptions{
	ID: "my-gitlab-repo",
	BaseRepo: storage.GenericGitBaseRepo{
		Provider:      "gitlab",
		Owner:         "your-group",
		Name:          "your-repo",
		DefaultBranch: "main",
	},
	DefaultBranch: "main",
})

curl "$CODE_STORAGE_BASE_URL/repos" \
  -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "default_branch": "main",
    "base_repo": {
      "provider": "gitlab",
      "owner": "your-group",
      "name": "your-repo",
      "default_branch": "main"
    }
  }'

For a self-hosted provider, add upstreamHost / upstream_host:

const repo = await store.createRepo({
  id: 'my-gitea-repo',
  baseRepo: {
    provider: 'gitea',
    owner: 'your-org',
    name: 'your-repo',
    defaultBranch: 'main',
    upstreamHost: 'git.example.com',
  },
  defaultBranch: 'main',
});

repo = await storage.create_repo(
    id="my-gitea-repo",
    base_repo={
        "provider": "gitea",
        "owner": "your-org",
        "name": "your-repo",
        "default_branch": "main",
        "upstream_host": "git.example.com",
    },
    default_branch="main",
)

repo, err := client.CreateRepo(context.Background(), storage.CreateRepoOptions{
	ID: "my-gitea-repo",
	BaseRepo: storage.GenericGitBaseRepo{
		Provider:      "gitea",
		Owner:         "your-org",
		Name:          "your-repo",
		DefaultBranch: "main",
		UpstreamHost:  "git.example.com",
	},
	DefaultBranch: "main",
})

curl "$CODE_STORAGE_BASE_URL/repos" \
  -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "default_branch": "main",
    "base_repo": {
      "provider": "gitea",
      "owner": "your-org",
      "name": "your-repo",
      "default_branch": "main",
      "upstream_host": "git.example.com"
    }
  }'

The response includes the internal repo_id. Use that value in the next step.

2. Store the Git credential

Create a credential record for the repository. Providers that accept a token alone do not need username.

await store.createGitCredential({
  repoId: repo.id,
  username: 'john_doe',
  password: 'YOUR_ACCESS_TOKEN_OR_PASSWORD',
});

await storage.create_git_credential(
    repo_id=repo.id,
    username="john_doe",
    password="YOUR_ACCESS_TOKEN_OR_PASSWORD",
)

_, err = client.CreateGitCredential(context.Background(), storage.CreateGitCredentialRequest{
	RepoID:   repo.ID,
	Username: "john_doe",
	Password: "YOUR_ACCESS_TOKEN_OR_PASSWORD",
})

curl "$CODE_STORAGE_BASE_URL/repos/git-credentials" \
  -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_id": "REPO_ID_FROM_CREATE_REPO",
    "username": "john_doe",
    "password": "YOUR_ACCESS_TOKEN_OR_PASSWORD"
  }'

3. Trigger the initial pull

await repo.pullUpstream();

await repo.pull_upstream()

err = repo.PullUpstream(context.Background(), storage.PullUpstreamOptions{})

curl "$CODE_STORAGE_BASE_URL/repos/pull-upstream" \
  -X POST \
  -H "Authorization: Bearer $CODE_STORAGE_TOKEN" \
  -H "Content-Type: application/json"

How Git Sync behaves

After you configure Git Sync, these rules apply:

git clone, git fetch, and git pull read from Code Storage
repo.pullUpstream() and POST /api/repos/{repo_name}/pull-upstream start an asynchronous refresh from the configured provider
Code Storage forwards each git push to the external Git host
A successful push starts a background sync to keep the Code Storage nodes current

Your app can use Code Storage as its stable endpoint. Code Storage still copies changes to and from the external host. Only pushes to the normal remote reach the external host. Pushes to the +ephemeral remote stay in Code Storage. A sync from the external host copies only refs/heads/* and refs/tags/*. Put machine state on ephemeral branches to keep it out of the upstream repository. Machine state includes agent snapshots, preview builds, and scratch commits.

Support

For help, email jacob@pierre.co.

Getting Started

Features

Workflows

Reference

Sync modes

Supported providers

Generic Git setup

1. Create the synced repository

2. Store the Git credential

3. Trigger the initial pull

How Git Sync behaves

Support

​Sync modes

​Supported providers

​Generic Git setup

​1. Create the synced repository

​2. Store the Git credential

​3. Trigger the initial pull

​How Git Sync behaves

​Related reference pages

​Support

Sync modes

Supported providers

Generic Git setup

1. Create the synced repository

2. Store the Git credential

3. Trigger the initial pull

How Git Sync behaves

Related reference pages

Support