Help / Gitsi / Getting started

Getting started with your Gitsi forge

This guide is for the admin of the forge, the person whose email was given with the order. In the examples, replace company.gitsi.dev with the address of your forge.

Activate your account

When the forge is delivered, it sends you an email titled « Récupérer votre compte » from gitsi@aleop.eu. The forge's emails are in French. The link inside works only once. It lets you choose your password. Nobody at Aleop knows it.

Your username is the part of your email before the @. For it@company.com, it is it.

The forge opens in French. To switch to English, open Paramètres, Apparence, then Langue. The steps below use the English labels.

If the link has expired, open the forge, click Forgot password? and ask for a new one.

Create accounts for your team

Nobody can sign up alone on your forge. You create the accounts, as site administrator.

Open Site Administration, then Identity & Access, User Accounts and Create User Account. Enter your colleague's username and email.

The form asks for a password. Type a long random one that you do not keep. Leave Require user to change password ticked and tick Send User Registration Notification. Your colleague receives an email titled « Votre compte sur » followed by the forge name, with a Choisir mon mot de passe button to choose their password.

To share repositories, then create an organization (New Organization) and Teams with Read, Write or Administrator Access on their repositories. Add the new accounts to them.

Create a token for Git

The forge only speaks Git over HTTPS. To clone and push from a computer, create a token instead of using your password.

In your Settings, open Applications, section Manage Access Tokens. Enter a Token Name, set repository to Read and Write, then click Generate Token.

The token is shown only once. Store it in your password manager.

On the first git clone, Git asks for a username and a password: give your username, then the token as the password.

git clone https://company.gitsi.dev/organization/repository.git

Import your repositories from GitHub or GitLab

First prepare a personal access token on GitHub or GitLab, with read access to the repositories you want to bring over. Without it, only the Git code is migrated.

In the forge, open the + menu at the top right, then New Migration. Choose GitHub or GitLab. Paste the repository address in Migrate / Clone From URL and the token in its field.

Tick the Migration Items you want to keep: issues, pull or merge requests, labels, milestones, releases or wiki. Choose the Owner, yourself or an organization, then Migrate Repository. Repeat for each repository.

A Git server inside your internal network cannot be reached from the forge. In that case, push the repository from a computer that can reach both.

The secrets of your pipelines do not follow the migration. Create them again in the repository settings, under Actions, Secrets.

Run a first pipeline

Gitsi reads workflows in the GitHub Actions format. Put a YAML file in .gitea/workflows/. If that folder does not exist, the forge reads .github/workflows/. A repository imported from GitHub therefore keeps its pipelines, and they start on the first push.

For a test, push this file as .gitea/workflows/test.yaml:

name: First pipeline
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello from Gitsi"

Check the result

Open the Actions tab of the repository. The job goes through Waiting and Running, then shows Success. Each step has its own log.

Actions written as uses: actions/checkout@v4 are fetched from github.com, as on GitHub. An action that calls a service specific to GitHub needs some changes: this first test is where you will see it.

If the Actions tab is missing, tick Enable Repository Actions in the repository settings.

Publish your packages and images

The forge has a package registry. Among other formats, it accepts container images and generic files. Create a token for it (step 3) with package set to Read and Write.

For an image, log Docker in to the forge with your username and this token, then name the image after its owner, yourself or an organization. The included runner has no Docker: build the image on a computer.

docker login company.gitsi.dev
docker tag my-image company.gitsi.dev/organization/my-image:1.0
docker push company.gitsi.dev/organization/my-image:1.0

Upload a generic file

An archive, a binary or an installer is uploaded with curl. Use --upload-file: an upload with --data-binary is refused. We tested it with files up to 200 MB.

Published packages appear in the Packages tab of their owner. From the package page, Link this package to a repository also shows it in the repository.

curl --user username:token --upload-file tool.zip \
  https://company.gitsi.dev/api/packages/organization/generic/tool/1.0/tool.zip

The runner included with your forge

Aleop installs a runner for your forge. It serves all your repositories, with nothing to set up on your side. You can see it in Site Administration, Actions,Runners. It accepts three values for runs-on:ubuntu-latest, ubuntu-24.04 and ubuntu-22.04.

	Gitsi	Gitsi Plus
Jobs at the same time	1	2
CPUs per job	2	4
Memory per job	4 GB	8 GB
Maximum job duration	30 min	2 h
Minutes per month	2,000	unlimited

A job can reach the internet, not your private networks: it cannot deploy to an internal server. It has no access to Docker either: a step that builds an image with docker build fails.

Need help?

Our support team can walk you through the setup. Write to us at support@aleop.eu.