GitHubOpen FerrisGit

What FerrisGit does today

Everything on this page ships today. What is planned is on the roadmap.

The application interface and its documentation are in French for now.

Repositories and groups

Host code under your own account or inside a hierarchy of groups, and decide who can do what.

  • Repositories owned by a user, or nested inside groups and subgroups
  • Public or private; the description and the visibility can be changed afterwards
  • Reader, Contributor and Maintainer roles, per repository or per group
  • Git over HTTP(S): clone, fetch and push with your username and a personal access token
  • Repository stars and language statistics
FerrisGit: the file list of a repository, with its last commitOpen the full screen

Merge requests

Review happens on the diff, and the whole conversation stays in one place.

  • Threaded inline comments
  • Code suggestions that can be applied from the interface
  • Approvals and change requests
  • Conflict detection
  • A timeline of everything that happened
FerrisGit: a review thread on a line of a merge request, with the reply field and the Resolve buttonOpen the full screen

Issues

Track the work next to the code.

  • Labels and milestones
  • Assignees
  • A kanban board with four states
FerrisGit: two columns of the kanban board, with the cards of the issuesOpen the full screen

CI/CD

A built-in engine, configured by a file in the repository.

  • Pipelines described in .ferrisgit-ci.yml at the root of the repository
  • Docker runners (a small ferrisgit-runner binary that polls the server) or Kubernetes, where each job runs as a Pod
  • Per-repository variables, encrypted at rest (Docker runners only)
  • Per-job caches (Kubernetes only)
FerrisGit: a running pipeline, stages as a stepper and jobs as linked nodesOpen the full screen
.ferrisgit-ci.yml
stages: [lint, test]

jobs:
  format:
    stage: lint
    image: rust:1
    script:
      - rustup component add rustfmt
      - cargo fmt --all -- --check

  clippy:
    stage: lint
    image: rust:1
    script:
      - rustup component add clippy
      - cargo clippy --all-targets -- -D warnings

  test:
    stage: test
    image: rust:1
    needs: [format, clippy]
    script:
      - cargo test --all-targets

Public pages and search

Open a project to people who do not have an account.

  • Visitors browse public repositories read-only: catalogue, README, files, commits and releases
  • Release files can be downloaded without signing in
  • Signed-in users get search, in-app notifications and a personal dashboard
FerrisGit: the catalogue of public repositories, readable without an accountOpen the full screen

Documentation

Built into the application, at /docs.

  • Open to everyone, signed in or not
  • A user guide, the CI/CD reference, administration and self-hosting, and the REST API reference
  • Written in French, with search
FerrisGit: a page of the built-in documentation, with the navigation treeOpen the full screen

How it is made

The same instance as on the home page. The numbers open the matching tabs and sections.

Architecture of a FerrisGit instanceIsometric drawing. A Git client and a browser talk to one Rust binary, ferrisgit-api, made of the api, application, domain and infrastructure crates. The binary stores its data in PostgreSQL and in Git repositories on disk, and runs pipeline jobs either through a ferrisgit-runner on a Docker host or as Pods in a Kubernetes cluster. An orange line follows a push to its jobs. Seven numbered circles lead to the tiles of the page.api application domain infrastructure ferrisgit-runner ferrisgit-api: one binary ferrisgit-runner Git client HTTPS, username + token no SSH yet Browser signed in, or anonymous on public pages api REST API, Git over HTTP, web interface domain entities and ports, no I/O application use cases infrastructure adapters: PostgreSQL, git, Docker, Kubernetes, SMTP, webhooks PostgreSQL accounts, issues, pipelines; migrations run at startup Git repositories on disk, wikis included Docker host the runner polls every 5 s by default, one job at a time, in a container Kubernetes cluster one Pod per job, created by the server git push pipeline created jobs polls for jobs

Fig. 1 One instance. The orange line follows a push from the client to the jobs it starts.

  • request or storage
  • a push, to its jobs
  • the runner polls
  • a numbered tile of this page

Wikis, webhooks, accounts and deployment

Accounts and administration

Multi-factor authentication is not optional.

  • Mandatory for every account: authenticator apps (TOTP), passkeys (WebAuthn) and single-use backup codes
  • Free registration behind an administrator switch, or accounts created by e-mail invitation
  • Administration: users and invitations, instance settings, usage metrics and a health page

Webhooks

Tell other tools when something happens.

  • Signed requests (HMAC-SHA256) for merge request, collaborator, pipeline and issue events
  • Secrets encrypted at rest
  • No retries and no delivery log yet: both are on the roadmap

Wikis and releases

Documentation and deliverables stay with the code.

  • Each wiki is stored as a Git repository of its own
  • Releases carry attached files

Under the hood

What you deploy, and what it needs.

  • One Rust binary (axum) serves the REST API, the Git protocol and the Angular web application
  • PostgreSQL 18 for the data; repository contents on the server's disk
  • Docker Compose or a Helm chart for Kubernetes; image masmarino/ferrisgit
  • A hexagonal architecture, split across five Cargo crates

Not there (yet)

These are on the roadmap. None of them exists today.

  • Git over SSH and deploy keys: Git is served over HTTP(S) only
  • Protected branches: a Contributor can push to any branch of the repository
  • Code-quality scanning and security analysis, including on merge requests
  • Forks and merge requests between repositories, squash and rebase merges
  • Single sign-on (OIDC, LDAP)
  • An interface in English, Italian, Spanish and German, and a theme setting: it is in French today and follows the system theme
  • A link with ArtiFerris
See the roadmap

Try it, then run your own.

The public instance shows the product. Your instance keeps your code.

Open FerrisGitInstallation guide