# 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/<you>/<repo>.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/<you>/<repo>.git
# Username: <you>   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 <you>         # Password: vec_…
docker build -t localhost:3000/<you>/<repo>:latest .
docker push localhost:3000/<you>/<repo>:latest
docker push localhost:3000/<you>/<repo>/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/<you>/<repo>.wiki.git
cd <repo>.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
`/<you>/<repo>/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 <you>:vec_… \
  http://localhost:3000/<you>/<repo>/releases/download/v1.0.0/app-linux-x64.tar.gz
curl -X DELETE -u <you>:vec_… http://localhost:3000/<you>/<repo>/releases/download/v1.0.0/app-linux-x64.tar.gz
```

Downloads are `GET /<owner>/<repo>/releases/download/<tag>/<file>` (or
`/releases/latest/download/<file>` for the newest release that isn't a pre-release)
and support ranges, so interrupted downloads resume. Source code is at
`/<owner>/<repo>/archive/refs/tags/<tag>.zip` (or `.tar.gz`; branches and commits
work too). Private repositories need a token (`-u <you>: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/<number>/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`.