Setting up your remote

Fastest path — the in-app setup page. Your fogwall deployment serves a Setup page in the dashboard (the help / quick-start icon in the top bar, reachable without logging in) that generates copy-pasteable git config for this deployment, with the real hostnames already filled in. By default it reroutes only your pushes to fogwall (via git’s pushInsteadOf) and leaves your clones and fetches going straight to the upstream — so read-only access is unaffected and you don’t need it at all if you only clone or fetch. It offers both a one-paste global form and an explicit per-repository form. The manual per-remote steps below are the same thing done by hand.

The proxy URL is structured as:

http[s]://<proxy-host>/<mode>/<provider-host>/<owner>/<repo>.git

For example, if you normally push to https://github.com/myorg/myrepo, the proxy remote is:

https://fogwall.corp.example.com/server/github.com/myorg/myrepo

The /server/ prefix was previously /push/ (when this mode was called store-and-forward). Remotes using /push/ still work — it is a deprecated alias — but new remotes should use /server/.

Add it as a new remote (recommended — keeps your direct-to-GitHub remote as a fallback):

git remote add proxy https://fogwall.corp.example.com/server/github.com/myorg/myrepo

Then push via the proxy:

git push proxy main

Credentials in the remote URL

The git push path (/server/ and /proxy/) uses HTTP Basic authentication — this is what the git protocol requires, and it matches what the upstream SCM expects. Your upstream PAT is the password; the username can be any non-empty string — me, git, your name — it is not used for identity resolution (see Identity verification below). It must not be empty or the upstream SCM will reject the request. The exception is Bitbucket — see below.

This is separate from the dashboard: the dashboard login uses your proxy user account (via your org’s IdP or local credentials), not your SCM token. The two credential sets are independent — one is for git push, the other is for the web UI.

Embed credentials directly in the URL if your git credential helper does not pick them up automatically:

git remote add proxy https://me:ghp_yourtoken@fogwall.corp.example.com/server/github.com/myorg/myrepo

Or use git credential store / your OS keychain as you normally would.

Fetching from a public repository needs no credentials. When you clone or pull through the proxy, fogwall asks the upstream SCM whether that repository serves anonymous reads. If it does, your request goes through without a credential prompt. If it doesn’t — a private repository — you get the usual 401 challenge and your git client supplies the token, which fogwall forwards upstream.

Pushing always requires credentials, whatever the repository’s visibility, because fogwall forwards the push upstream using your own token.

Tip

Most credential helpers (macOS Keychain, Windows Credential Manager, git-credential-store) pin credentials to a hostname. git authenticates to the proxy host, not the upstream — so if you have previously authenticated directly to the upstream (e.g. github.com), that credential won’t be reused for the proxy; git looks for one stored under fogwall.corp.example.com instead. Either let git prompt on the first push and your helper store it under the proxy host, store a separate entry for the proxy host yourself, or embed the token in the remote URL as shown above. For local development environments that are frequently recreated, embedding the token in the URL is simpler than managing keychain entries.

Tip

Pushing to more than one provider through the same proxy? The proxy serves every provider under one hostname, differing only by URL path (/server/github.com/… vs /server/codeberg.org/…), but credential helpers key on hostname alone — so one stored credential would be reused for all of them. Run git config --global credential.https://fogwall.corp.example.com.useHttpPath true to key credentials on the full URL (host + path) instead, so each provider gets its own entry.

Warning

Bitbucket only: the username in the remote URL must be your Bitbucket account email address (e.g. you@company.com). This is required for identity resolution — see the Configuration Reference for details.

Pushing with a fogwall credential

On providers your administrator has set up for it, you can push through server mode (/server/…) without a token of your own:

1. On your dashboard profile, link your account for the provider on the SCM Identities tab.
2. On the Git Credentials tab, create a credential, named for the machine you will use it from. Copy it: it is shown once.
3. Use it as the password of your server-mode remote. fogwall runs its checks, then forwards the push as your linked account.

The credential works only against fogwall; the provider does not recognise it, and fogwall refuses it anywhere but a server-mode remote. To keep git from offering it to other remotes on the fogwall host, such as a /proxy/ fetch remote that carries your own token, key server-mode credentials by path:

git config --global credential.https://fogwall.corp.example.com/server.useHttpPath true

Git then asks for the credential on the first push to each repository, and your credential helper keeps it for that repository.

Without a credential helper (git config credential.helper prints nothing), git asks on every push. Put the credential in the remote URL instead; git keeps it in the repository’s .git/config, in plain text:

git remote add fogwall https://fogwall:fgw_…@fogwall.corp.example.com/server/github.com/myorg/myrepo.git

If a push is refused because your linked account is missing, can no longer be used, or was linked without permission to push, link it again from your profile. Rotate or revoke a credential from the same tab; a credential you revoke stops working at once.

Pushes queued for review

Where your administrator has turned on deferred forwarding, a push made with a fogwall credential does not wait for review. Once fogwall’s checks pass, git reports the push as done and fogwall prints its push ID:

remote: ✅  Push received and queued for review
remote: 🔑  Push ID: 4d6196fb-...
remote:    Review at: https://fogwall.corp.example.com/dashboard/push/4d6196fb-...
remote:    fogwall forwards it upstream once approved; the push record shows the outcome.

The push reaches the provider only after it is approved. Until then, fetching through fogwall still shows the branch where it was, even though your local remote-tracking branch has moved. Pushing more commits to the same branch queues them too; they are forwarded in order.

If forwarding fails, the push record says why and shows Forward now, which you can use once the cause is fixed, for example after linking your account again. A push that can no longer be applied upstream, because the branch moved in a way yours does not build on, has to be pushed again.

Required token scopes

The proxy calls the SCM API to resolve your identity. Your PAT needs at least: