Getting Started with Vetrix

This guide covers the essentials: creating your first repository, pushing code, and inviting a collaborator.

Prerequisites

A Vetrix account (register at /register or ask your admin to create one)
Git 2.x installed locally
An SSH key pair, or use HTTPS with a personal access token

1. Add your SSH key

Navigate to Settings → SSH Keys and paste your public key (~/.ssh/id_ed25519.pub or ~/.ssh/id_rsa.pub).

Verify connectivity:

ssh -T git@<vetrix-host>
# Welcome to Vetrix, <username>!

If you prefer HTTPS, generate a personal access token at Settings → Access Tokens and use it as your password when cloning.

2. Create a repository

Go to the New Repository page or use the API:

curl -X POST https://<vetrix-host>/api/v1/repos \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "description": "My first project", "private": false}'

3. Push an existing project

cd my-project

# If starting fresh
git init
git add .
git commit -m "Initial commit"

# Add the remote and push
git remote add origin git@<vetrix-host>:<username>/my-project.git
git push -u origin main

4. Clone an existing repository

SSH:

git clone git@<vetrix-host>:<username>/my-project.git

HTTPS:

git clone https://<vetrix-host>/<username>/my-project.git
# Username: your Vetrix username
# Password: your personal access token

5. Invite a collaborator

In the repository UI go to Settings → Collaborators, search by username, and choose a role:

Role	Permissions
`read`	Clone, view issues and merge requests
`triage`	Read + manage issues and labels
`write`	Triage + push branches, create merge requests
`maintain`	Write + manage settings, protected branches
`admin`	Full control including transfer and deletion

Or via API:

curl -X PUT https://<vetrix-host>/api/v1/repos/<owner>/<repo>/collaborators/<username> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"permission": "write"}'

6. Open a merge request

Push a feature branch:

git checkout -b feature/my-change
# ... make changes ...
git push origin feature/my-change

Then open a merge request in the UI or via API:

curl -X POST https://<vetrix-host>/api/v1/repos/<owner>/<repo>/pulls \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "My change", "head": "feature/my-change", "base": "main"}'

7. Configure CI/CD

Add a .ci/pipeline.yml file to your repository root to enable automated pipelines.

Quick example:

stages:
  - build
  - test

build:
  stage: build
  image: golang:1.22
  commands:
    - go build ./...

test:
  stage: test
  image: golang:1.22
  commands:
    - go test ./...

Jobs are top-level keys — there is no jobs: wrapper. Commands go under commands:, not script:.

For a step-by-step walkthrough see cicd/first-pipeline.md. For branch filters, manual triggers, and scheduled runs see cicd/triggers.md. Full YAML schema: cicd/pipeline-reference.md.

Next steps

git-protocol.md — SSH configuration, key types, HTTP authentication
cicd/pipeline-reference.md — Full pipeline YAML schema
mcp/connect-ai-assistant-oauth.md — Connect Claude.ai / Gemini to a repository's MCP server over OAuth
../admin-docs/cicd/runners.md — Register and manage CI runners
../admin-docs/admin/ — Instance administration (admins only)