Quick Start

After installation and completing the setup wizard, you land on the GitRiver home page. This section covers how to create your first repository, set up SSH, configure CI/CD, and invite colleagues.

Creating Your First Repository

Via the Web Interface

1. Click the ”+” button in the top right corner -> Repository
2. Fill in:
   • Name - Latin letters, digits, hyphens (e.g., my-project)
   • Description - a brief project description (optional)
   • Visibility - public (everyone can read) or private
3. Optionally check:
   • Initialize README - creates a README.md file with the description
   • .gitignore - choose a template for your language
   • License - MIT, Apache 2.0, and others
4. Click “Create”

Cloning to Your Machine

After creation, copy the URL from the interface:

# HTTPS (with login/password or token)
git clone https://git.example.com/username/my-project.git

# SSH (after setting up a key - see below)
git clone ssh://git@git.example.com/username/my-project.git

From an Existing Project

If you already have a local git repository:

cd my-existing-project
git remote add origin https://git.example.com/username/my-project.git
git push -u origin main

---

Setting Up SSH Keys

SSH lets you work with git without entering a password on every push/pull.

1. Create a key (if you don’t have one)

ssh-keygen -t ed25519 -C "your@email.com"

2. Copy the public part

cat ~/.ssh/id_ed25519.pub

3. Add it to GitRiver

1. Click your avatar in the top right corner -> “Settings”
2. In the left menu, select “SSH Keys”
3. Click “Add SSH Key”
4. Paste the public key contents, enter a name
5. Click “Save”

4. Verify

git clone ssh://git@git.example.com/username/my-project.git

---

Setting Up GPG Keys

GPG keys allow you to sign commits to verify authorship.

1. Click your avatar -> “Settings” -> “GPG Keys”
2. Click “Add GPG Key”
3. Paste your public GPG key (gpg --armor --export your@email.com)
4. Configure git to sign commits:

git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true

---

Access Tokens

Tokens are needed for automation: scripts, external CI/CD systems, docker login.

Creating a Personal Token

1. Click your avatar -> “Settings” -> “Tokens”
2. Click “Create Token”
3. Specify:
   • Name - what this token is for (e.g., “CI server”)
   • Scopes - what is allowed:
     • Read repositories
     • Write to repositories
     • Read registry (docker pull)
     • Write to registry (docker push)
   • Expiration - when the token expires
4. Click “Create” and save the token - it is shown only once

Usage

# As a password for git clone
git clone https://username:gtr_pat_xxxxx@git.example.com/owner/repo.git

# As an Authorization header
curl -H "Authorization: Bearer gtr_pat_xxxxx" https://git.example.com/api/v1/user

# For docker login
docker login git.example.com -u username -p gtr_pat_xxxxx

---

Your First CI/CD Pipeline

GitRiver has a built-in CI/CD system with YAML configuration.

1. Create a workflow file

In the root of your repository, create the file .gitriver/workflows/ci.yml:

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    image: node:22
    steps:
      - run: npm ci
      - run: npm test

This means: on every push to main or when a pull request is created - run the test job in a node:22 container.

2. Push to the repository

git add .gitriver/workflows/ci.yml
git commit -m "Add CI configuration"
git push

3. View the result

1. Open the repository in GitRiver
2. Go to the “CI/CD” tab (rocket icon in the repository menu)
3. You will see the running pipeline with the test job
4. Click on the job - logs will open in real time

For CI to work, Docker must be available on the GitRiver host (or the Docker socket must be mounted into the container). See the CI/CD Pipelines section for details.

---

Inviting Users

Open Registration

By default, registration is open. Users can register themselves on the login page. To disable: Administration -> System -> uncheck “Allow registration”.

Creating a User as Administrator

1. Open Administration (in the top menu)
2. Go to the “Users” section
3. Click “Add User”
4. Fill in the name, email, password

Groups (Organizations)

Groups unite users and repositories:

1. Click ”+” -> “Group”
2. Enter a group name (e.g., backend-team)
3. Add members with roles: Owner, Maintainer, Developer, Reporter, Guest

See the Users and Groups section for details.