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:

   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:

   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.