# Actions

## Running workflows

1. Register a runner under **Settings → Runners** (for all your repositories) or under a repository's **Settings → Runners**, and copy its token.
2. Start it on any machine with Node.js 18+ and git:
   ```bash
   curl -fsSLO http://localhost:3000/vectrum-runner.mjs
   node vectrum-runner.mjs --url http://localhost:3000 --token vrn_…
   ```
3. Add `.vectrum/workflows/ci.yml` and push:
   ```yaml
   name: CI
   on:
     push:
       branches: [main]
     workflow_dispatch:        # adds a "Run workflow" button
   jobs:
     test:
       runs-on: self-hosted    # labels the runner must have
       steps:
         - run: npm ci
         - name: Test
           run: npm test
   ```

Supported: `on: push` (with `branches`, `tags`, `paths` and their `-ignore` forms), `pull_request` (with `types`, by default `opened`, `synchronize` and `reopened`, and `branches`/`paths` filters on the base branch and changed files), `pull_request_review`, `issues` and `issue_comment` (with `types`: `issues` has `opened`, `edited`, `deleted`, `closed`, `reopened`, `assigned`, `unassigned`, `labeled`, `unlabeled` and `status_changed`), and `workflow_dispatch`; `env` at every level; jobs with `runs-on`, `needs`, `timeout-minutes`; steps with `run`, `name`, `shell`, `working-directory`, `env`, `if: success()/failure()/always()`, `continue-on-error` and `timeout-minutes`. The repository is checked out before the first step (`uses: actions/checkout` is accepted and skipped). Other `uses:` actions, `${{ }}` expressions, matrices, services and secrets are not supported; steps get `VECTRUM_*` environment variables (`VECTRUM_SHA`, `VECTRUM_REF_NAME`, `VECTRUM_REPOSITORY`, …) instead. Runs started by an event also get `VECTRUM_EVENT_ACTION`, `VECTRUM_EVENT` (its JSON payload), and `VECTRUM_ISSUE_NUMBER`, `VECTRUM_PR_NUMBER`, `VECTRUM_HEAD_REF`, `VECTRUM_BASE_REF` and `VECTRUM_COMMENT_ID` where they apply. Pull request runs check out the pull request's head; issue and comment runs the default branch, whose workflow files decide what runs (so an issue can't change the code a workflow runs).

Runners poll the server over HTTPS (`/api/runner/*`), so they need no inbound port. Every runner has the labels `self-hosted`, its OS (`linux`, `macos`, `windows`) and architecture (`x64`, `arm64`), plus any you give it. Each job gets a short-lived, read-only token that can only clone its own repository. Steps run as the user that started the runner, with no sandbox, so only run runners for repositories whose workflows you trust.