GitRoot

  1# From "baby to teenager" GitRoot become a forge
  2
  3## If you only have 5 minutes
  4
  5Previously, GitRoot served as a **Source Code Management (SCM)** system, allowing you to create Git repositories and manage access permissions. However, GitRoot was never intended to be _just_ an SCM. With this **v0.3.0** release, it evolves into a full-fledged **forge**.
  6
  7To activate this new capability on your instance, [follow the administrator section](#for-admin-activating-an-executor). To start using it as a user, [see the user section](#for-user-using-the-hop-plugin).
  8
  9The introduction of **executors** brings a crucial new feature: the [report and reporter plugin API](#plugin-api-report-and-reporter). This API allows any plugin to provide informational feedback to the user. **Important:** avoid reporting low-level technical details here (use the `log` and `logError` APIs for that). The initial implementation uses this feature to display command statistics (CPU, memory, etc.) from the new `hop` plugin in a clean table via the `grafter` plugin.
 10
 11With the new `hop` plugin, GitRoot now supports 3 languages (Go, TypeScript, Rust) across 4 compilers (Go, TinyGo, Rust, AssemblyScript). Setting up a development environment for this polyglot stack is complex, and keeping it updated is even harder, unless you have the right tools. For this iteration, I have selected [mise](https://mise.jdx.dev/) as the default tool for [managing the GitRoot dev environment](#gitroot-bets-on-mise).
 12
 13Beyond technical features, a new focus has been placed on [communication](#communication-and-community-building). You can now follow daily progress on our new fediverse instance (@forge@gitroot.dev), engage in direct chat on matrix (#gitroot:matrix.org), and read a new blog post detailing concrete ways to contribute today.
 14
 15Finally, I discuss [Apex](#apex-a-better-web-experience) and many [other tiny but useful things](#and-others-useful-updates).
 16
 17## In-depth Details
 18
 19### For admin: activating an executor
 20
 21When you update GitRoot to `0.3.0` a new configuration block will appear in the `.gitroot/forgeConfig.yml` file of your `root` repository:
 22
 23```yml
 24execconf:
 25  baremetal:
 26    enabled: false
 27  bwrap:
 28    enabled: false
 29    user: nobody
 30    uid: 65534
 31    gid: 65534
 32    robind: []
 33    bind: []
 34  container:
 35    enabled: false
 36    bin: podman
 37  ssh:
 38    enabled: false
 39    hosts:
 40      - user: myUSer
 41        address: 127.0.0.1
 42        port: 22
 43        publickey: ssh-ed25519 AAAAC3NzaC1...
 44```
 45
 46> You can enable multiple executors, but GitRoot will only use the first one enabled, checking them in this order: `bareMetal`, `bwrap`, `container` and then `ssh`. If you activate an executor, remember to also add the `hop` plugin, as it is the only known plugin designed to utilize them.
 47
 48#### Bare Metal: simplest but most dangerous
 49
 50The `bareMetal` executor runs commands directly on the host machine. It requires no external dependencies and should work on any hardware. Be extremely cautious: users of your GitRoot instance will gain the ability to execute arbitrary code on the host.
 51
 52#### Bubblewrap (bwrap): lightweight sandboxing
 53
 54The `bwrap` executor introduces a lightweight container (sandbox) between executed commands and the host, similar to the technology used by [flatpack](https://flatpak.org/). To use it, you must install the [bubblewrap](https://github.com/containers/bubblewrap) application.
 55
 56By default, GitRoot configures `bwrap` to use the `nobody` user for restriction, though this can be changed. You can also define bindings between your host and the commands running inside the container. For example, `robind: ["/var/log/caddy/access.log"]` would allow a job to execute `cat /var/log/caddy/access.log`.
 57
 58#### Container: heavyweight but most flexible
 59
 60The `container` executor enables the execution of commands within [podman](https://podman.io/) or [docker](https://www.docker.com/) containers, allowing your users to run any OCI image. The only requirement for the administrator is to install either [podman](https://podman.io/docs/installation) or [docker](https://www.docker.com/). Remember to change the `bin` property to `docker` if that is your chosen runtime.
 61
 62GitRoot includes a useful feature for containers: if the user provides a path to a `Containerfile` or `Dockerfile`, GitRoot will automatically build the image before running commands inside it.
 63
 64#### SSH: remote execution (alpha)
 65
 66The `ssh` executor allows commands to be executed on a remote host via a standard SSH connection. You simply provide the standard SSH connection details. This executor should be considered the most alpha of all options (and yes, all others are also considered alpha).
 67
 68### For user: using the `hop` plugin
 69
 70To execute a build (or command execution), users must activate the `hop` plugin and configure its execution rules:
 71
 72```yml
 73- url: /home/rmaneschi/projects/gitroot/app/testsuite/../plugins/hop/hop-0.0.1.wasm
 74  name: hop
 75  version: 0.0.1
 76  active: true
 77  run:
 78    - path: "*"
 79      branch:
 80        - "*"
 81      when:
 82        - add
 83        - mod
 84      write:
 85        git: []
 86        web: []
 87        exec:
 88          - command: cat
 89      configuration:
 90        exec:
 91          build: ""
 92          cmds:
 93            - args:
 94                - README.md
 95              cmd: cat
 96          env: []
 97```
 98
 99Add all desired commands for the plugin to call in `run.write.exec`.
100
101Then in `run.configuration.exec`:
102
103- set environment variables via `env` (e.g., `"MY_ENV=my_val"`)
104- specify the `build` property (only for the `container` executor) to use an existing image (e.g., `docker.io/bash:5.3.3`) or to build one from a file (e.g., `/my/path/to/Containerfile`)
105- define the commands and arguments to execute under `cmds`
106
107### Plugin api report and reporter
108
109Occasionally, plugins need to communicate important information to the user. For instance, the `ladybug` plugin might need to report invalid metadata. In traditional forges, a web interface serves this purpose, but GitRoot operates without a fixed UI.
110
111Past considerations included sending emails (a solution often disliked by developers) or leveraging external communication methods like RSS via the `pollen` plugin (introduced in v0.2.0) or the Fediverse via a Go-to-Social instance. As always, GitRoot aims to provide options rather than dictate a single solution.
112
113To allow reporting without forcing a communication channel, I've created two new plugin APIs.
114
115Report: plugins call this API with a severity level (`info`, `warn`, or `error`) and an array of strings to display. GitRoot stacks all reports for every commit and plugin.
116
117Reporter API: after reports are collected, GitRoot calls all plugins that implement the `Reporter` interface.
118
119Currently, the `grafter` plugin is the only known reporter; it adds the collected reports to the graft output. This two new API opens up a wide range of possibilities for future versions. I have several ideas, but I encourage you to [share yours](../contact.md)!
120
121### GitRoot bets on mise
122
123Managing a diverse development environment that spans Go, TypeScript, and Rust can be a significant hurdle. In this iteration, I have standardized on mise as the official tool for managing the GitRoot dev environment. This choice simplifies installation and ensures all dependencies remain correctly updated for development.
124
125This choice seems to be a good one, as we welcome a new contributor who has already integrated some common tasks using `mise`. Thanks to their efforts, we can now simply run `mise run build` to compile GitRoot or `mise run test` to execute all tests.
126
127### Communication and community building
128
129Alongside the technical work for v0.3.0, a focused effort was put into non-technical tasks to improve communication with the community.
130
131To allow you to follow daily progress and current thoughts, I have set up a [GoToSocial](https://gotosocial.org/) (Mastodon) instance. You can find the official account at `@forge@gitroot.dev` or directly at [https://gts.gitroot.dev](https://gts.gitroot.dev). This is the best place for real-time updates.
132
133I also established a direct chat room on [matrix](https://matrix.org/), accessible via [https://matrix.to/#/#gitroot:matrix.org](https://matrix.to/#/#gitroot:matrix.org). Feel free to stop by to ask questions or just say hello.
134
135I've added a [contact](../contact.md) page to ensure you can easily find a way to reach me. It includes multiple options such as email, mastodon, or matrix for direct chat. Please don't hesitate to come say "hi"!
136
137Finally, I published a blog post titled ["How to help building GitRoot 11-2025"](./how-to-help_en_11-2025.md). The purpose of this post is to present you with concrete, immediate contribution opportunities, rather than speculating on future possibilities. If you wish to get involved, this is the place to start.
138
139### Apex a better web experience
140
141The Apex plugin receives numerous bug fixes and quality of life improvements:
142
143- favicon support: a favicon can now be added via the configuration
144- styled 404 page: the 404 error page now correctly uses the site's CSS
145- HTML metadata configuration: I have added configuration options for HTML metadata, which is useful for SEO and for including specific tags like `og` (Open Graph) or `fediverse` metadata
146- menu highlighting: the current page in the navigation menu is now highlighted
147- lightweight template: added some variables in header and footer templates
148
149**Breaking:** previously, the `apex` plugin rendered markdown metadata as small blocks at the top of the page by default. With this version, it will no longer render this metadata unless the markdown page explicitly includes `apexRenderMetadatas: true` in its front matter.
150
151### And others useful updates
152
153Although this article is already quite long, I want to briefly mention several smaller yet important tasks completed in this release.
154
155#### ForgeConf update
156
157The parameters `externalsshaddr` (default value `ssh://localhost:4545/`) and `externalhttpaddr` (default value `http://localhost:4546/`) have been added to ensure the display of correct external urls to users. These addresses are notably used by the `apex` plugin generate proper public links. They are kept separate from the internal `sshaddr` and `httpaddr` because your GitRoot instance might be configured to listen internally (on `127.0.0.1`) while being reachable externally through a reverse proxy.
158
159#### Integrated updater
160
161I've added a preliminary implementation for an integrated updater. This feature will handle breaking changes gracefully. For this release, I've added some new parameters to `forgeConf.yml`, the integrated updater will handle these by setting standard values that should not affect your current user instance setup.
162
163#### Rust and WASM
164
165While integrating Rust, I discovered that the WASM (and specifically WASI Preview 1) target does not permit exporting the standard `free` and `malloc` functions, which GitRoot requires. I've added an option to rename these functions to `gitrootAlloc` and `gitrootFree`, resolving this compatibility issue.