CORS for Browser Sync

The browser version of Surebeans runs at https://surebeans.net. Browsers block requests from that origin to your git forge unless the forge returns a specific set of CORS headers (Cross-Origin Resource Sharing). This page explains how to satisfy that requirement.

You have two options:

1. Use a CORS proxy (default). Surebeans routes git traffic through a proxy that adds the headers for you. This is the only option for hosted forges you cannot configure, such as github.com and gitlab.com.
2. Enable CORS on your own forge. If you self-host (Gitea, Forgejo, GitLab, or similar), you can let the browser talk to your forge directly and turn the proxy off.

Enable CORS on your own forge

Two kinds of request go to your forge, both from your app origin:

• REST API Paths containing /api/ list files, download raw content, upload, delete, create the repository, set the default branch.
• Git smart-HTTP: These check for repo existance and send and receive git history. The paths end in /info/refs, /git-upload-pack, and /git-receive-pack.

Both must allow your app origin. An easy mistake to make is enabling CORS only on the API. Sync then fails because Surebeans checks for repo existnce using /info/refs.

What to allow

Common mistakes:

• Missing headers. If your Access-Control-Allow-Headers reply is missing even one of the above headers, the browser blocks the request, even if the preflight returned 204. As an alternative to a fixed list, you can echo the request’s Access-Control-Request-Headers back in Access-Control-Allow-Headers. See below for examples.
• Duplicate headers. If both your forge and a reverse proxy in front of it add Access-Control-Allow-Origin, the browser sees a duplicate header and rejects the response.

Examples

These illustrate the idea. Adapt them to whatever sits in front of your forge.

Caddy

@cors_preflight method OPTIONS
handle @cors_preflight {
    header Access-Control-Allow-Origin "https://surebeans.net"
    header Access-Control-Allow-Methods "GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS"
    # Echo the requested headers back, so nothing the client sends is rejected.
    header Access-Control-Allow-Headers "{http.request.header.Access-Control-Request-Headers}"
    header Access-Control-Max-Age "86400"
    respond 204
}
header Access-Control-Allow-Origin "https://surebeans.net"
reverse_proxy your-forge:3000

Nginx

location / {
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin "https://surebeans.net" always;
        add_header Access-Control-Allow-Methods "GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS" always;
        # Echo the requested headers back, so nothing the client sends is rejected.
        add_header Access-Control-Allow-Headers "$http_access_control_request_headers" always;
        add_header Access-Control-Max-Age 86400 always;
        return 204;
    }
    add_header Access-Control-Allow-Origin "https://surebeans.net" always;
    proxy_pass http://your-forge:3000;
}

Gitea / Forgejo app.ini

[cors]
ENABLED = true
ALLOW_DOMAIN = https://surebeans.net,https://www.surebeans.net
ALLOW_METHODS = GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS
ALLOW_HEADERS = Authorization,Content-Type,Git-Protocol,Cache-Control,Pragma,X-Requested-With

GitLab

Self-hosted GitLab does not expose a general CORS setting for the git and API routes. You’ll need to use a reverse proxy.

Verification

In Surebeans

Once your forge returns CORS headers:

1. Go to https://surebeans.net
2. Open the remote in Sync and click Edit.
3. Uncheck Route git traffic through CORS proxy.
4. Click Sync Now.

From the command line

A correct setup returns 204 and an Access-Control-Allow-Origin matching your origin.

curl -i -X OPTIONS \
  -H "Origin: https://surebeans.net" \
  -H "Access-Control-Request-Method: GET" \
  -H "Access-Control-Request-Headers: authorization" \
  "https://git.example.com/you/my-budget.git/info/refs?service=git-upload-pack"

If you see 403, 404, or no Access-Control-Allow-Origin header, the git routes are not covered yet.