# Using Vectrum ## Pushing over SSH 1. Add your public key (`~/.ssh/id_ed25519.pub`) under **Settings → SSH keys**. 2. Check the connection: `ssh -T -p 2222 git@localhost` 3. Push: ```bash git remote add origin ssh://git@localhost:2222//.git git push -u origin main ``` ## Pushing over HTTPS Generate a token under **Settings → API tokens** and use it as the password when git asks (any username works): ```bash git clone http://localhost:3000//.git # Username: Password: vec_… ``` Anonymous users can clone public repositories without a token. ## Pushing container images Log in with an API token as the password (read & write to push), then tag and push images under a repository's name. Image names are lowercase: ```bash docker login localhost:3000 -u # Password: vec_… docker build -t localhost:3000//:latest . docker push localhost:3000//:latest docker push localhost:3000///worker:1.0 # more images in one repository ``` Anyone who can read the repository can pull; anonymous users can pull images of public repositories. The repository has to exist before you push. Docker only talks plain HTTP to `localhost`; anywhere else, serve Vectrum over HTTPS (or add the host to Docker's `insecure-registries`). A reverse proxy in front of Vectrum must pass large request bodies through (e.g. nginx `client_max_body_size 0;`). ## Writing the wiki Start the first page under a repository's **Wiki** tab, or clone the wiki and push Markdown files to it (the first push creates it): ```bash git clone ssh://git@localhost:2222//.wiki.git cd .wiki && echo "# Hello" > Home.md git add Home.md && git commit -m "Add Home" && git push ``` A page is named after its file: `Getting-Started.md` is *Getting Started* at `///wiki/Getting-Started`, in whichever folder it is. `Home` is the wiki's front page, `_Sidebar.md` and `_Footer.md` are shown around every page, and `[[Getting Started]]` or `[[the guide|Getting Started]]` link to a page. Pushes to a wiki don't start workflows. Repository names can't end in `.wiki`, since that's where wikis are cloned from. ## Publishing releases Draft one under a repository's **Releases** tab, or upload files from a script with a read & write API token. Uploading to a pushed tag that has no release yet publishes one for it; uploading a file again replaces it: ```bash git tag v1.0.0 && git push origin v1.0.0 curl -fT dist/app-linux-x64.tar.gz -u :vec_… \ http://localhost:3000///releases/download/v1.0.0/app-linux-x64.tar.gz curl -X DELETE -u :vec_… http://localhost:3000///releases/download/v1.0.0/app-linux-x64.tar.gz ``` Downloads are `GET ///releases/download//` (or `/releases/latest/download/` for the newest release that isn't a pre-release) and support ranges, so interrupted downloads resume. Source code is at `///archive/refs/tags/.zip` (or `.tar.gz`; branches and commits work too). Private repositories need a token (`-u :vec_…` or `-H "Authorization: Bearer vec_…"`). To publish from a workflow, give the runner's environment a token (workflows have no secrets) and `curl` the files in a job that runs `on: push: tags`. ## Forks *Fork* on any repository you can read makes a copy you own, linked to the original. Push to it, then *Contribute* on its front page (or *New Pull Request* on the original, picking the fork as the repository with the changes) opens a pull request on the original. The pull request lives there: its commits are copied into the original as `refs/pull//head` (like GitHub), follow every push to the fork's branch, and stay readable after the fork is deleted. Deleting a fork closes its open pull requests; deleting a repository that has forks makes them forks of what it was forked from. Workflows run on the original's own runners, so a pull request from a fork only starts them by itself when its author has push access there. Otherwise its *Checks* say so, and someone with push access looks at the changes and clicks *Run Workflows*, for each new commit. Agents fork with `fork_repository`, open the pull request with `create_pull_request` and `head_repo`, and catch up with `sync_fork`.