Menu

Git Deploy

Basil's server holds a bare Git repository you push to, served over HTTPS at /.git. Clone it, edit, git push to share with the team — and move the release branch (live) to publish, which checks the release and makes it live. Push-to-deploy with nothing but Git.

Basil-only. The Git endpoint is part of the Basil server. It is on whenever the site has a site.git repository, which basil --init <dir> --server creates on the deployment machine — there is nothing to enable.

Setting a site up for the first time? The Deployment page has numbered walkthroughs for the two ways a site and a server meet — server first, or laptop first. This page is the Git side of it: keys, roles, and what the endpoint will and will not accept.

Quick Start

1. Get an API key. basil --init <dir> --server creates the first admin account and prints its key once, so on a freshly built server you already have one. For anyone else (see Running Basil):

basil users create --name Sam --email sam@example.com --role editor
basil apikey create --user usr_abc123... --name "MacBook Git"   # → bsl_live_abc123… (save it!)

2. Clone your live site (the key is the password; the username selects a stored credential and is ignored by Basil):

git clone https://sam@yourserver.com/.git mysite

3. Share work:

cd mysite
# edit…
git add . && git commit -m "Update homepage"
git push                        # stored on the server, published to nobody

4. Publish:

basil publish                   # review the commits and files, confirm, then it deploys

basil publish runs in the clone: it shows what is about to go out, reports how far the live site has drifted, asks before pushing (--yes skips it, --dry-run stops at the plan), and streams the server's deploy output. Underneath it is a push of the release branch, so raw git push origin live still works; a release that fails validation is rejected with the live site left unchanged, and the server warns (never rejects) about unformatted .pars files, naming basil fmt -w.

--dry-run never pushes, but on a first publish (a project whose history is unrelated to the server's starter site) it may run a git fetch while classifying the state — needed to tell a genuine first publish from an ordinary divergence. It downloads objects and updates remote-tracking refs, but pushes nothing.

Authentication & Roles

Git access uses API keys via HTTP Basic Auth (key as the password).

Operation Required role
Clone / pull any authenticated user
Push editor or admin

Revoke a compromised key with basil apikey revoke <id> — no need to touch user accounts.

See Also