GitRoot

  1---
  2title: 0.3.0
  3og:title: 0.3.0
  4og:description: From "baby to teenager" GitRoot become a forge
  5description: From "baby to teenager" GitRoot become a forge
  6og:image: ""
  7date: 2025/12/20
  8emoji: 🔖
  9---
 10
 11# From "baby to teenager" GitRoot become a forge
 12
 13## If you only have 5 minutes
 14
 15Previously, 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**.
 16
 17To 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).
 18
 19The 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.
 20
 21With 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).
 22
 23Beyond 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.
 24
 25Finally, I discuss [Apex](#apex-a-better-web-experience) and many [other tiny but useful things](#and-others-useful-updates).
 26
 27## In-depth Details
 28
 29### For admin: activating an executor
 30
 31When you update GitRoot to `0.3.0` a new configuration block will appear in the `.gitroot/forgeConfig.yml` file of your `root` repository:
 32
 33```yml
 34execconf:
 35  baremetal:
 36    enabled: false
 37  bwrap:
 38    enabled: false
 39    user: nobody
 40    uid: 65534
 41    gid: 65534
 42    robind: []
 43    bind: []
 44  container:
 45    enabled: false
 46    bin: podman
 47  ssh:
 48    enabled: false
 49    hosts:
 50      - user: myUSer
 51        address: 127.0.0.1
 52        port: 22
 53        publickey: ssh-ed25519 AAAAC3NzaC1...
 54```
 55
 56> 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.
 57
 58#### Bare Metal: simplest but most dangerous
 59
 60The `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.
 61
 62#### Bubblewrap (bwrap): lightweight sandboxing
 63
 64The `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.
 65
 66By 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`.
 67
 68#### Container: heavyweight but most flexible
 69
 70The `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.
 71
 72GitRoot 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.
 73
 74#### SSH: remote execution (alpha)
 75
 76The `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).
 77
 78### For user: using the `hop` plugin
 79
 80To execute a build (or command execution), users must activate the `hop` plugin and configure its execution rules:
 81
 82```yml
 83- url: /home/rmaneschi/projects/gitroot/app/testsuite/../plugins/hop/hop-0.0.1.wasm
 84  name: hop
 85  version: 0.0.1
 86  active: true
 87  run:
 88    - path: "*"
 89      branch:
 90        - "*"
 91      when:
 92        - add
 93        - mod
 94      write:
 95        git: []
 96        web: []
 97        exec:
 98          - command: cat
 99      configuration:
100        exec:
101          build: ""
102          cmds:
103            - args:
104                - README.md
105              cmd: cat
106          env: []
107```
108
109Add all desired commands for the plugin to call in `run.write.exec`.
110
111Then in `run.configuration.exec`:
112
113- set environment variables via `env` (e.g., `"MY_ENV=my_val"`)
114- 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`)
115- define the commands and arguments to execute under `cmds`
116
117### Plugin api report and reporter
118
119Occasionally, 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.
120
121Past 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.
122
123To allow reporting without forcing a communication channel, I've created two new plugin APIs.
124
125Report: 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.
126
127Reporter API: after reports are collected, GitRoot calls all plugins that implement the `Reporter` interface.
128
129Currently, 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)!
130
131### GitRoot bets on mise
132
133Managing 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.
134
135This 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.
136
137### Communication and community building
138
139Alongside the technical work for v0.3.0, a focused effort was put into non-technical tasks to improve communication with the community.
140
141To 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.
142
143I 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.
144
145I'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"!
146
147Finally, 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.
148
149### Apex a better web experience
150
151The Apex plugin receives numerous bug fixes and quality of life improvements:
152
153- favicon support: a favicon can now be added via the configuration
154- styled 404 page: the 404 error page now correctly uses the site's CSS
155- 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
156- menu highlighting: the current page in the navigation menu is now highlighted
157- lightweight template: added some variables in header and footer templates
158
159**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.
160
161### And others useful updates
162
163Although this article is already quite long, I want to briefly mention several smaller yet important tasks completed in this release.
164
165#### ForgeConf update
166
167The 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.
168
169#### Integrated updater
170
171I'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.
172
173#### Rust and WASM
174
175While 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.