Blog of gitroot.dev

0.5.0 plugins

rmaneschi@gmail.com (Romain Maneschi) — 2026/10/30

What is GitRoot without its plugins?

In the release 0.5.0 blog post I have only talked about the GitRoot core code. But GitRoot is a forge where plugins take a lot of space. In the future I want to decouple GitRoot and its plugins. I hope to stabilize the plugin-sdk, release them, so that you will be able to create your own plugins.

But today, GitRoot and officials plugins are linked by the version. So let me explain what they can do in this new version.

All plugins are compatible with the 0.5.0

All plugins are compatible with the 0.5.0 plugin-sdk. What does that mean? Every time you see a BREAKING and plugin in the changelog, it means I had to change the code of the plugin-sdk and recompile plugins with that new code (sometimes I need to change the code of the plugin, sometimes not). So when you see compatible with gitroot plugin-sdk 0.5.0 in the changelog of a plugin, it means that the plugin is good to run inside this GitRoot version.

I’ll present here only the most important features, for details you can read the changelog of each plugin.

Firefly in zig

First, let me introduce Firefly: add URLs to call and Firefly will generate beautiful status pages for them. Yes, it’s a status page directly integrated into your forge, so no need to depend on a third-party service. Of course, it’s useful only if the app observed is not on the same host as your forge. So it’s totally useless for GitRoot. But as an example, you can see the status page of gitroot on gitroot.

I’m proud because it’s my first code in the zig language. Not everything is perfect, of course, but I love the language itself, so I will make other plugins and rework them when needed. If you are Zig lovers too, don’t hesitate to help me.

Silo, lots of new things

Silo: from files and metadata, Silo generates indexes to find files more easily. I have added a lot of features into this milestone.

You can now sort the rendered list by the files which each item links to. I use it to render all the TODOs in GitRoot, in the todo board.

Now Silo can render the list directly to the web. Useful to not encumber the git repositories with redundant lists. For example, I use it to render plugins in alphabetical order or by scope.

Furthermore, as you can see in the plugins page, Silo can now render lists by alphabetical group. To render them, I have added a new property groupBy which allows you to tell Silo which property you want to group your list items by.

The groupBy, title, desciption and to properties can contain $variable. These variables will be interpreted when Silo renders the list. So, for example, if you want to render the title of a list with a special metadata of the content, you can:

1- selects:
2    - "purl: pkg:gitroot/[^/]+/([^@]+)"
3    - "purl: pkg:gitroot/([^/]+)"
4  title: Plugins for scope $select[1]

This means that you select the scope and name of the PURL plugin and render the name into the title. A way to add metadata into the rendered list is to use the new metadata property.

The silo plugin use the standard regexp from go to extract selects.

With all of that, dynamic boards can be created. From files to index files with metadata, you can create indexes of indexes. An example is the scope page. Silo takes all plugins from the plugins/name directory, generates a page which is an index of all scopes, and then generates a page for each. Today only the gitroot scope exists, but I hope for a lot more in the future.

Not related, but a good addition to the Silo plugin is the custom data format. It permits to render each element in the format you want (by default, only list and table were possible). I use it to render the blog posts index.

To find examples on how to configure all of that, look at the silo configuration of gitroot.dev instance.

Apex is the web view

A lot of tiny, but useful things have been added to the apex plugin. Apex is the plugin that renders the files from your git repository to the web. You configure the header, footer, menu, and it takes care of assembling all of that with your <main> content. Today it only renders HTML and markdown (through the apex_markdown plugin).

So, the first addition is to export a renderHtml function. With that in place, all other plugins can render something with your header, menu, footer and the right CSS. Without it, most plugins rendered only the content of the page withtout <head>. For example, see what Firefly looks like without Apex:

A new layout has been added: slide. Previously, the property layout could be filled with a path and Apex used it (if it didn’t exist, Apex created it with the default one inside). But if instead of a path you set issue, Apex will render all matching paths with a particular layout: see any issue, Apex has added metadata before the page, and grouped all content inside an <article> instead of a <br> like you can see in the original markdown page.

Following this strategy, the new slide layout renders the page with the slide.css and groups all page breaks into <section> as required by the CSS.

If Apex renders markdown through the apex_markdown plugin, how is that possible? All the magic resides in a new property added in the apex_markdown plugin. This property is horizontalRuleMetadatas, with that, Apex can instruct the markdown renderer how to render page breaks.

Another addition to apex_markdown is the ability to render callouts for blockquotes and details/summary. To render a callout, use this in your markdown:

1> [!NOTE]
2> This a note callout.

Which renders on the web as:

This a note callout.

Today, the possibilities are (but in the future I want to make them configurable):

1var calloutColor = map[string]string{
2	"[!NOTE]":    "#006ac7",
3	"[!WARNING]": "#be4700",
4	"[!ERROR]":   "#f00",
5}

Following the same philosophy, to render details/summary:

1> [!DETAILS] This is a summary
2> This is the details

Which renders on the web as:

This is a summary

This is the details

Finally, in a last-minute change before the release, I have added the metadata toc: true to be able to render a table of contents, because the v0.5.0 article was too long.

Grafter diff

An important (in UX, not size) change in the grafter plugin is that it now renders commit diffs from the start. Grafter is the plugin responsible for managing contributions, it permits discussing what has been done and finally merging (or not) the contribution.

Previously, Grafter displayed diffs only after the property status was set to review. But that was confusing. Now, from the start, it shows diffs.

And now that the Apex plugin can render summary/details, Grafter uses it to render reports from other plugins. You can see the result in the graft of this post.

Pollen render content

If you use pollen, you can delete the property link as it is calculated directly from the forge configuration. Pollen is the plugin responsible for communicating with the outside of your forge. Today it uses only RSS.

But the biggest change is the ability to render the content of files in addition to the commits. Previously, Pollen rendered only commit metadata (title, description, author…). Now it can render the content of files to have a true RSS for your issues, grafts, or even blog posts. Don’t forget to subscribe to the blog rss of this instance.

What next?

One big thing I wanted to do before the 0.5.0 release (but ran out of time) was to change how Apex renders links. Today all links are absolute with a trick in the html page (<base href="https://gitroot.dev/">), I have done that because the 404 page needs to be rendered everywhere in the repository. Unfortunately, that makes too many bugs with bad linking. So I want to revert that as priority one (maybe keep the trick only for the 404 page).

After that, I want to better render Git in the web. A lot of missing concepts need to be rendered, commit, branch are the first ones. So I will add an apex_git plugin. And if I have time, an apex_gitroot plugin to render specific GitRoot files like users.yml, plugins.yml or repositories.yml.

I have grouped multiple related issues in the apex board. That will be my priority, but of course, as I change my mind a lot, that’s not a promise of what will be done.

Special thanks to Ryuno-Ki from the #gitroot:matrix.org Matrix room for reviewing and correcting this article. Want to help with future posts? Join us in the room!

0.5.0

rmaneschi@gmail.com (Romain Maneschi) — 2026/10/05

Move slowly, and take care of things

These days, everything moves too fast. They push thousands of lines of AI generated code every hour, deploying it without even understanding how it works. But with GitRoot, I want to do the exact opposite. I want to take my time, savor every architectural choice, and thoroughly enjoy writing every line of code by hand. It’s a project that is deeply close to my heart: a space for freedom far away from the rat race of metrics. So yes, we move at our own pace: slowly, and take care of things.

Thanks to lonugem for the title idea

If you only have 5 minutes

Breaking PURL

I’m sorry to say that the first feature I want to talk about is a big breaking one. I know, I know, on the homepage of GitRoot I say “no headaches to upgrade my forge”…. but this time you will… If you are not happy, you can contact the support and get a refund for the previous year and a 100% discount for the next one :D

Joking aside, you need to replace your plugin URL with a PURL one. ECMA PURL is a specification to produce “a standardized URL-based syntax that uniquely identifies software packages”.

This corresponds to the following change:

1- url: https://gitroot.dev/releases/0.4.0/ladybug-0.0.4.wasm
2- checksum: sha256:7409837469ce89d5c9fd8dd48236764650f48523ff4d81295967154977a01635
3- name: ladybug
4- version: 0.0.4
5+ purl: pkg:gitroot/gitroot/ladybug@0.0.5?checksum=sha256:afb22a26e7d489d72db0a2305d433a3c3ac2692959ba2412011c0d759b4c8518&registry=https:%2F%2Fgitroot.dev%2Freleases%2F0.5.0
6  active: true

GitRoot will download $registry/$scope-$name-$version.wasm, so it will be https://gitroot.dev/releases/0.5.0/gitroot-ladybug-0.0.5.wasm for the example. And then compare the downloaded WASM binary with the checksum provided in the PURL.

Look in the plugins registry to find the exact purl for each plugin.

To know why, how and more read purl details.

A lot of people have discovered GitRoot

First show, first lobste.rs/HN links, first video… Yes, more and more people are talking about GitRoot. Discover where.

Not conclusive

Sometimes you spend more time on a subject than you thought. And sometimes, after all of this time spent, you don’t have what you wanted to have at the start… That is the case for the sdkgenerator experiment. It should “just” generate Rust, TS, Zig code from Golang… “Just”, lol, I never finished it. Maybe someone wants help? Read the full sdkgenerator story.

Before it’s too late

How to prevent spam with a forge without registration? This question was asked by NLnet 2 years ago (no, they don’t fund GitRoot, I was rejected). Two years later I have the answer, not perfect, but it’s a start. I added two new properties: one in .gitroot/forgeConf.yml of your root repository, NbMaxBranchesPerProjectBeforeRejectingAnonymous, which is the number of branches before rejecting anonymous pushes. And one in .gitroot/repoConfiguration.yml of all your repositories, NbMaxBranchesBeforeRejectingAnonymous, which serves the same purpose but for a single project. Read why and see the full example

My new favorite language…. until the next one

After Golang, AssemblyScript, and Rust, the plugin-sdk is now accessible for the Zig language. I continue to add new languages and discover how they work. This one was especially refreshing in its implementation. Read more

Plugins needs more power

Talking about the plugin-sdk, they all receive a lot of new features. They can now schedule jobs, make http requests, and configure plugins during CallFunc. I have also simplified the initialization part. Read details

Sftp to save the web

How to add images to the web without cluttering Git? That was the problem I had to tackle before adding slideshows to GitRoot. SFTP came to the rescue, and with ~200 lines of code, it’s now possible. I love when a simple, established protocol allows you to fix a complicated feature. Read more to know how to enable it.

How many bugs?

A lot of bug fixes have been done. Let me explain some interesting ones.

In-depth Details

PURL breaking details

At the beginning of this story, I only wanted to add a scope for plugins. That way, if you install a plugin with gitroot as the scope, you can think “it looks less dangerous” than anyother scope. Just like I suspect less @angular than some odd Node.js package (well, the npm ecosystem is maybe a bad example for that… but the only one right now).

So, my simple idea was to transform url: https://gitroot.dev/releases/0.4.0/ladybug-0.0.4.wasm into something like url: https://gitroot.dev/releases/0.4.0/gitroot-ladybug-0.0.4.wasm, so that a gitroot-*.wasm is affiliated with me. In the registry, I can show the scope.

Another example is if someone forks ladybug and wants to release it in the registry. Previously there was no option to do that, so adding a scope seemed to be the best choice.

During my research on a way to model this scope, I found the ECMA-427 Package-URL (PURL) specification. PURL stands for Package URL (I call them Plugin URL), a way to express many packages as a URL. What a perfect fit for the GitRoot plugin system!

This is how a PURL is represented: scheme:type/namespace/name@version?qualifiers#subpath. In GitRoot, I use only pkg:gitroot/$scope/$name@$version?checksum=$checksum&registry=$urlToDownload (maybe a default registry like https:%2F%2F%2Fgitroot.dev will be added in a next version, I’m not sure about that for now). There is no specification about what a registry should do to implement the GitRoot specification. For now, GitRoot will download $urlToDownload/$scope-$name-$version.wasm, and that’s all.

Thanks to PURL, I can delete a lot of other properties in the .gitroot/plugins.yml file, like version, checksum, and name. I also use it a lot in the code to refer to a plugin. Previously I only used the name, but now I use a full PURL. So, for example, if a plugin wants to call another plugin (thanks to the CallFunc API), it can define it as pkg:gitroot/$scope/$name (to mean all possible versions), or an exact version with pkg:gitroot/$scope/$name@$version. Adding a checksum and even a registry is also possible.

That was a big refactor to do, but I’m pretty happy with the result.

GitRoot communication

A lot has occured during this summer, on the communication side too.

I want to thank Adullact and particularly Matthieu for letting me present the first show at the Adullact congress. The video is only in French without subtitles: Souveraineté : Savez-vous vraiment qui contrôle vos logiciels ?. It was a great two-day congress, I talked to a lot of passionate people. And for once, they weren’t developers.

Then the first appearance on lobste.rs and Hacker News occurred. Thanks hasnep for sharing, you can follow the initial exchange on my GoToSocial. As the image shows, there was a spike in the number of visitors, emails, and questions asked on the platforms and in private. That was a great moment to experience.

After the mentions on these platforms, some other cool articles popped up (I won’t link them as they are principally AI-generated slop). But there was also a video showing how to run GitRoot in a nanoVM: https://www.youtube.com/watch?v=g5nW9g5T4wU.

Another particular point of pride was the first mention by Andrew Nesbitt in the blog article Issues in the Repo. Thanks to Damien for talking about GitRoot to Andrew. Since you deleted the toot, I guess you don’t want to be cited here. If that’s not the case, contact me.

And GitRoot has been added to AlternativeTo. I don’t know if this will lead to anything, but hey, I’m right alongside GitHub and GitLab :P

SdkGenerator full story

This experiment comes from a bored developer who didn’t want to use LLMs, but also didn’t want to rewrite the same models/objects/structs (call that what you want) four times. When I want to add a new function to the plugins-sdk, I do it in one language, and then, when it works, I need to rewrite it in all the other languages (more on that in the “Modifying the API in the SDK Plugin” blog article).

In my day job, I love to build tools that generate code. I have written a tool that takes Kotlin as input and generates TypeScript output. Then I wrote a tool that generates complete Angular components from Kotlin enums (yeah, bored of writing a form select from an enum). And finally, it generates complex Angular services from Spring annotations (when you are very bored, a lot of things can be generated).

So it’s naturally that I started to write a tool that generates TS, Rust, and Zig from Go. But the experience is not conclusive… A lot of language specifics cannot easily be shared by a tool. I’m not giving up… I just have more interesting priorities (yes, I’m less bored on GitRoot than at my work ^^). But if this is the kind of thing you like, yes, you, reading that, please reach out to me, and I’ll explain all that I did and how you can take it further.

By the way, I discovered another kind of tool that does a similar job: WIT. It’s not an official spec from the W3C, but since it’s from the Bytecode Alliance, it’s big enough to use. I have quickly looked at it, and the engine I use for Wasm is not really compatible for now. But I’m keeping that in mind; it could be a replacement for SdkGenerator if nobody (including me) wants to do the job.

Max anonymous branches

When a lot of people started to talk about GitRoot, one thing haunted my nights: what if someone builds a simple script that clones GitRoot, creates 1,000 branches, and pushes them? I would need to git push origin :branch for every single one of them. You don’t need to register to contribute to GitRoot, and that’s one of its strengths, but also one of its weaknesses.

How to make that impossible without blocking all the beauty of GitRoot? One day, a simple solution came to me (yes, I love imagining scenarios running against me). Why not limit the number of branches from anonymous users? It’s simple after all: I need to count the number of branches made by anonymous users, and if it exceeds a limit, I stop accepting them. However, people I have added to my repo because of a previous contribution can still push new branches. That is what I added, but… there is always a but… counting the number of branches is lightweight, but counting the number of branches from an anonymous user is really expensive. Life is full of choices, and I made one.

When the branch limit is reached, we stop accepting anonymous contributions. That means if you set 10 as the maximum and you make 20 branches, nobody else can contribute. Yes, it’s not perfect, but it’s way better than having nightmares every night.

If an admin configures the forge with NbMaxBranchesPerProjectBeforeRejectingAnonymous=10, that means when a project has 10 branches (who added them doesn’t matter), the next anonymous user (not present in .gitroot/users.yml) will be rejected. Of course, all known users can continue to create as many branches as they want.

A project can set a lower number, NbMaxBranchesBeforeRejectingAnonymous=5, but if the number is bigger, it will have no effect (e.g., if set to NbMaxBranchesBeforeRejectingAnonymous=15, GitRoot will use 10 as set by the forge administrator).

A neat trick: setting NbMaxBranchesBeforeRejectingAnonymous=0 blocks all anonymous pushes. Alternatively, you can use the Not accepting anonymous contribution guide. The main difference is the error message: the first gives anonymous branches not allowed, while the latter shows you can't write in $branchName.

Zig plugin-sdk

With every release, I try to add a new plugin-sdk language. This time I picked zig because it is a language that natively manages Wasm and WASI, so I was pretty sure I would finish this implementation.

I loved the error system, compared to Rust (optionals) and Go (multiple returns), Zig chose an in-between solution with ! and some language keywords. But what totally blew my mind is the comptime feature, where the compiler can become an interpreter for compilation output. Amazing idea, I am pretty sure a lot of things will follow this path.

Long story short, I spent a long time discovering the language, and it was a very good time for me (it changes your perspective, seeing the same problem solved another way)… but nothing related directly to GitRoot.

As with all the plugin-sdks, there is unfortunately no way for you to use it yet. I don’t release them in registries until the API is stable, and a lot of breaking changes are coming in the next release.

PluginSdk improvements

Regarding the plugin-sdk, here are a lot of new capabilities for plugins to use:

schedule: you can allow a plugin to be called at a scheduled time. The format is a cron expression with 5 segments as <minute> <hour> <day> <month> <weekday>. Example:

1- purl: pkg:gitroot/gitroot/firefly@0.0.1?checksum=sha256:fae956f5cc9239a87b1c2a149a5466fec85476377de4ada33dda190edb3700c4&registry=https:%2F%2Fgitroot.dev%2Freleases%2F0.5.0
2  active: true
3  run:
4    - path: ""
5      branch:
6        - main
7      when: []
8      schedule: "* * * * *"

That means the firefly plugin will be executed on the main branch every minute. Refer to the gronx library documentation for cron expression details.

httpClient: plugins can make HTTP requests. I have added standard verbs (GET, PUT, POST and DELETE), if you need more, please let me know. You can also add headers as a map[string][]string. In the next version, I will add permission a plugin must request beforehand.

callFunc configuration: you can add a configuration for the called plugin within the caller plugin’s callFunc. This makes it possible to tell the called plugin what its configuration is in this context. Previously, an empty config was set, so the plugin’s defaults (if any) were used. Example:

1callFunc:
2  - pluginPURL: pkg:gitroot/gitroot/apex
3    funcName: renderHtml
4    configuration:
5      branchesDir: branches
6      favicon: logo.png
7      footer: <p>Start with <code>git clone ssh://gitroot.dev/</code> 🚀</p><small>Hosted with ❤️ by Gitroot</small>
8      generateGitWorktree: true
9      header: ...

init function, one to rule them all: I have refactored the init() function of the plugin-sdk to provide an initKind model.InitKind, which can be confhaschange, diff, schedule, or funccall. This lets the plugin know in which context it is running, and this architecture allows future hooks to be added without breaking the API.

pull-iterator: I have introduced pull-iterators to be able to group reports without sending all reports to the Wasm memory. In a future version, I will use this mechanism to transfer commits and files directly to Wasm.

Sftp feature

Users can access every repository’s web directory through SFTP. To do this, you can use the same SSH key that you use for your Git repository. When you log in with sftp -P $SshPort $SshAddress:/$repo/ (like sftp -P 4545 127.0.0.1:/repo1/), you will see the list of web representations for your repository. Anyone can do this, but only those in the “owner” section of .gitroot/users.yml have write access.

Be careful: this feature is in alpha, so don’t write scripts around it for now. I will probably change the directory hierarchy #d42a.

To enable this feature, you need to change activesftp: false to activesftp: true in .gitroot/forgeConfig.yml at the root repository of your instance. Don’t forget to restart GitRoot after that, otherwise the parameter will not be taken into account by GitRoot.

Some interesting bug fixes

Of course, a lot of bug fixes have been included in this release. I will present only the most interesting ones, and you can find a more complete list in the changelog and an even more thorough one in the commits.

The first annoying bug occurred when Grafter committed to a file, but Apex did not render that file if the Grafter plugin was placed after Apex in the configuration. In fact, even if you put Grafter before Apex, the bug persisted because Apex reports the rendering back to Grafter, meaning it missed that final report. Now, I have added a subsequent loop where plugins can only write to the web directory (and cache) but not to Git. This way, all plugins loop over commits and files to generate new commits, and only afterwards do we loop through all plugins to see if they have anything to write to the web (or cache) excluding Git to avoid an infinite loop.

Another annoying issue happened when you changed a plugin’s configuration, causing it to enter a worktree loop (looping over files in the worktree instead of commits). Consequently, the commits generated by this loop were not propagated to other plugins, causing widespread rendering misses on the web.

Finally, if you decided to add a plugin multiple times in your .gitroot/plugins.yml file (to have multiple configurations, for instance), only the first instance was actually loaded and executed. Now, you can include a plugin as many times as you want, with any configuration you choose, and they will all be executed.

What next?

New plugins, bug fixes, updates… Yes, until now this article was only about GitRoot, but what is GitRoot without its plugins? The immediate next thing I will do is write an article about what new plugin versions can do.

Then I will probably start working on:

Discover GitRoot without installing anything.
Create your own plugins with ease.
Transform GitRoot into a registry for (at least) Go, Rust, NPM and Zig.
Federation with GitRoot but also other forges.
Implement something for users (how to represent them).
Manage more Git functions in plugins (branch, pull, push, rebase).
Use pull-iterators to stabilise the plugin-sdk.
Easier configuration of plugins.
Auto-update of plugins.
New language plugin-sdk.
Air-gapped version of GitRoot.
Make every repository a gemini capsule.

If you compare this with the last v0.4 what next section, there are a lot more things. Every time I finish a feature (or don’t, see the plugin-sdk generator), I can add ten more new features to do. That’s why I love GitRoot, and that’s why I Move slowly, and take care of things.

Special thanks to Ryuno-Ki, Matthieu and ks from the #gitroot:matrix.org Matrix room for reviewing and correcting this article. Want to help with future posts? Join us in the room!

0.4.0

rmaneschi@gmail.com (Romain Maneschi) — 2026/04/22

The teenager starts building its own future

If you only have 5 minutes

A lot has been done in this new release of GitRoot. When I saw other FOSS projects claiming “this is the biggest release”, I thought it was a joke. But in fact, it’s true: every new release gets bigger and bigger. It’s just astonishing to start a sprint with almost zero ideas and, 4 months later, see all of this accomplished.

If you skim this article, don’t forget to check out the conclusion about “what’s next?”.

The thing i’m most proud of

Executors can finally build GitRoot! As I love to say: GitRoot can build GitRoot on GitRoot. And it was a pain to do. Read more.

The thing with the most visibility

The plugin registry is here! After a lot of reading and reflecting, I started this “epic story”. Today is only the beginning, but you can now find plugins directly at gitroot.dev/plugins. What’s next? Read more.

The thing that changes everything but was so simple

Previously, a branch (and graft) couldn’t be rendered on the web. The problem was: if I have an index.md in my git that renders at myinstance.com/index.html, anyone can create a branch. If a “bad user” comes along, changes everything in this file, creates a branch, and pushes for review, where should this file render? Certainly not at myinstance.com/index.html. Read more.

The thing that was more complex than I thought

Apex was a big plugin. Basically, it manages the rendering of your git files to the web. But over time, it started to grow out of control because of markdown, code, worktrees, emojis… A simple (in theory) solution was to split it into multiple plugins. Read more.

The things I’m just happy are done

No more mandatory signed commits! Well, it’s still better if you sign them, but this change means the .gitroot/init.sh has been ~~deleted~~ moved to a plugin. Read more.

Moving a file from git to web was hard, deleting a file was “not implemented”, and a lot of APIs were missing in the plugin-sdk. I got my hands dirty with all that, and now everything is running smoothly. Read more.

In-depth Details

Executor

When I started this feature, I just wanted a lightweight container to run make build and output the result as a gitroot-next canary binary. If I had known how much time and energy it would actually cost, I’m not sure I would have taken this road.

At first, I chose bubblewrap as a lightweight container, and immediately started building a container version. Then I realized I needed a bareMetal one. And then, I needed a way to run it on other machines, so ssh came along.

But when I launched it for the first time, I discovered that having make isn’t enough for GitRoot, I need Golang, Rust, TinyGo, and so on. “No problem,” I thought, “I’ll use mise to manage that.” But running mise install takes a lot of time (like 10-15 minutes on my computer). So, I built a cache system to ensure that hit only happens the first time.

Still not the end! After that, I needed to configure port numbers, so I built a complete environment variable system, and used it to configure some mise paths.

Is it finished? Not yet! To be able to move a binary generated from a bwrap environment to the web, it has to travel a lot. And by “a lot,” I mean moving it to a place where the plugin that launched the executor can access it: its own cache. Then the plugin needs to move it from there to the web. No problem, I just added a bunch of SDK API.

After all that, some commands finally started working… well, kind of. When I ran a bwrap or a container command, I couldn’t get the stats of what was happening inside. Having process stats is something I’m proud of (even if it’s still evolving in future versions), but seeing that bwrap reported 20 MB of RAM while the sub-process was actually consuming 80 MB was very frustrating. Furthermore, I needed a way to extract stats from the remote SSH executor.

I tried a lot of things, but ultimately, I chose to build an executor CLI to handle it. I now inject that binary inside your bwrap, container, or SSH environment. This little CLI launches commands, gathers system stats, command status, and logs. It packs everything into a well-formatted JSON and returns it to the executor in GitRoot. GitRoot then manages artifacts/caches and hands the result back to the calling plugin (probably hop), which tells you what’s happening. In this case, it reports back so the grafter plugin can include the info in the current graft.

Phew, is that enough now? It should be, but we’ll see how it performs in real-time on gitroot.dev. Not everything is finished: for example, the SSH executor doesn’t manage cache yet #94af and can’t use the container strategy #f050. You can’t run the executor on other architectures #4d49 yet, and I’m sure you’ll soon want a way to clean up temp directories #647f.

But hey, let’s celebrate what we’ve built before jumping into the next sprint!

Plugin registry

Until now, explaining GitRoot was always about “data in git and the plugin system”, but what exactly are the plugins? Where are they? What can they do? All of that was a bit mysterious. With this milestone, I’m answering some of those questions with a first shot at a registry. Be careful, though: this first version is just a “hand-written” preview of what it could be in the future. If you look at the source, you’ll see that everything is ready to be automated, but nothing is… yet.

I’m not entirely sure what you, as a consumer, want to see here. Probably an explanation of what the plugin does, some docs, and the available versions. But as a plugin creator, you likely want to manage all of that in your own repository instead of the gitroot.dev registry. I chose to keep the registry very light and put the details directly in the plugin’s directory to give you an idea of what your own repo could look like.

I’ll need to iterate on this. Even if I choose to embed package details in the registry, I still need to decide how: maybe via a JSON in your repo, maybe in the registry itself, or perhaps inside your package (WASM)? I don’t know yet what’s simplest for you and for the registry.

Anyway, I hope this registry helps you understand what a plugin is and how it shapes your forge. Some are small (ladybug), others are massive (apex), and some aren’t usable solo as they are dependencies for others (like apx_mermaid).

Since plugins are now decoupled from GitRoot, I’ve moved all changelogs from the general one to the individual plugin directories. This way, I’ll be able to release plugin versions independently of GitRoot (and vice versa). I hope to break the plugin API less often, even if I know I probably will in the near future. All of this paves the way for you to build your own plugins and I hope to see them in the gitroot.dev registry soon. Or, of course, you can just build your own registry!

Apex render branch

For as long as I can remember, this has been a problem with GitRoot: how to render arbitrary changes, especially deletions, on the web? I had imagined a lot of strategies. The last one was to render inside a directory named after the git tree ID (the abstract representation of a working directory). Then, I’d create a symlink between that tree and a main directory.

The idea was: if you push a file in a branch, git gives you a tree ID like a654fs. It would be represented as mydomain.com/myBranch/file -> mydomain.com/tree/a654fs/file. When you merged that branch, GitRoot would simply symlink the main directory to it: mydomain.com/file -> mydomain.com/tree/a654fs/file.

Elegant, but honestly, a total over-engineered mess. When I actually sat down to code this, I ended up adding just two lines to the apex plugin:

1if p.currentCommit.Branch != "" && p.currentCommit.Branch != p.config.defaultBranch {
2	path = filepath.Join(p.config.branchesDir, p.currentCommit.Branch, path)
3}

And… yeah, that was enough. I’ve been overthinking this since the very beginning of GitRoot! Rendering files from branches into a dedicated branches directory… It’s simple. Just like GitRoot should be.

So, what does it mean in practice? The file is now rendered at myinstance.com/mybranch/index.html and the graft at myinstance.com/mybranch/grafts/mybranch.html. How did I not think of something this simple before?

Plugin deps

The catalyst for this development was the apex plugin. At over 3 MB, it was by far the largest plugin. It was packed with configuration, specifically a bunch of booleans to toggle features. Furthermore, I needed to render Markdown in other plugins, like pollen, to create a proper RSS feed. It became clear to me: this plugin needed to be split into smaller, more specialized ones.

So, I started building the apex_markdown plugin, then apex_code, and next week apex_mermaid. But what I hadn’t fully anticipated was the sheer amount of work required to make it all work together.

What if a dependency is missing? What if a method is deprecated or removed in a newer version? To handle this, I’ve chosen to make all dependencies entirely optional for now. It’s an easy choice to make today, but I might change my mind tomorrow, after all, there’s a reason most package managers handle version ranges and resolution.

This new architecture allows for adding tons of features without rebuilding an entire plugin. Imagine adding Org-mode or RST support: you just swap out apex_mardown instead of touching the whole stack. It also allows other plugins to reuse existing behaviors effortlessly.

With this in place, I’m not even sure if I’ll keep the report system, which was an other way of passing information between plugins.

Sigma plugin

Signed commits should be the default in git today. With SSH signing, it’s easy to do, and everyone should use it because impersonating a name and email is way too easy in git. When I started GitRoot, I made signed commits mandatory before allowing a push. But in fact, making signatures mandatory should be a choice for the instance owner. GitRoot is all about the freedom to choose how your forge works for you.

Furthermore, a friend told me he preferred signing with PGP and already had his setup ready. So why force him to use a .gitroot/init.sh? It’s frustrating when you want to test a new forge and you’re forced to run random sh commands, even if it’s just to configure your git client.

With this release, I have completely removed init.sh from GitRoot itself. But of course, as always, I’ve created a plugin to “almost” recreate this feature. The only difference is: instead of refusing your commit when you push, the stigma plugin will simply report unsigned or badly signed commits in your graft.

Now, you have the choice to accept unsigned commits in your repo. You can even ignore the whole signing topic entirely if you don’t install the stigma plugin.

That said, I’m still convinced that signing commits should remain the default.

FS plugin-sdk

After finishing all the executors features, one thing was still missing: the ability for a plugin to move a file from one path to another. As explained in this blog post, even though a plugin sees one single filesystem, GitRoot actually uses three different ones: one for cache (a directory), one for the web (a subdirectory), and a virtual one for the git working directory.

I was missing several methods in both the Rust and TS SDKs, and the existing API was poorly designed with inconsistent naming. I decided to redesign everything and added a lot of new methods accessible via FS in the SDK. Now, you can copy, move, delete, replace, and write files in every filesystem. Moving and copying can now be done between different filesystems, making it easy to make a file accessible on the web even if it originated from git or the cache.

I have marked all old methods as deprecated, and they will be removed in the next version of GitRoot (or more specifically, the plugin-sdk, though they share the same release number for now).

What next?

I have a massive roadmap for GitRoot (in no particular order):

Discover GitRoot without installing anything.
Create your own plugins with ease.
Transform GitRoot into a registry for (at least) Go, Rust, and NPM.
Plugins should be usable via PURL.
Plugins can send/receive HTTP requests.
Plugins can be scheduled.
Rebase go-git to take advantage of their performance improvements.
Generate the plugin SDK automatically.
Add plugin SDKs for (at least) Zig, Kotlin, and Python.

Yeah, I could go on all night. And those are just core GitRoot features. I haven’t even mentioned making instances to build projects in hosted environments. I haven’t talked about specific plugins (sending a “toot” on commit, managing secrets with age, translating your app…). I haven’t even touched on federating GitRoot with other GitRoot instances, or with Forgejo, SourceHut, or Radicle.

All of that is possible, and I’m confident it will be accessible in the future. But “when”? That’s the real question. If you think you can help in any way (coding, of course, but also management, communication, or just to brainstorm), please let me know.

This is only the beginning. GitRoot will get better and better with every release.

0.3.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/12/20

From “baby to teenager” GitRoot become a forge

If you only have 5 minutes

Previously, 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.

To activate this new capability on your instance, follow the administrator section. To start using it as a user, see the user section.

The introduction of executors brings a crucial new feature: the report and reporter plugin API. 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.

With 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 as the default tool for managing the GitRoot dev environment.

Beyond technical features, a new focus has been placed on communication. 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.

Finally, I discuss Apex and many other tiny but useful things.

In-depth Details

For admin: activating an executor

When you update GitRoot to 0.3.0 a new configuration block will appear in the .gitroot/forgeConfig.yml file of your root repository:

 1execconf:
 2  baremetal:
 3    enabled: false
 4  bwrap:
 5    enabled: false
 6    user: nobody
 7    uid: 65534
 8    gid: 65534
 9    robind: []
10    bind: []
11  container:
12    enabled: false
13    bin: podman
14  ssh:
15    enabled: false
16    hosts:
17      - user: myUSer
18        address: 127.0.0.1
19        port: 22
20        publickey: ssh-ed25519 AAAAC3NzaC1...

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.

Bare Metal: simplest but most dangerous

The 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.

Bubblewrap (bwrap): lightweight sandboxing

The bwrap executor introduces a lightweight container (sandbox) between executed commands and the host, similar to the technology used by flatpack. To use it, you must install the bubblewrap application.

By 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.

Container: heavyweight but most flexible

The container executor enables the execution of commands within podman or docker containers, allowing your users to run any OCI image. The only requirement for the administrator is to install either podman or docker. Remember to change the bin property to docker if that is your chosen runtime.

GitRoot 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.

SSH: remote execution (alpha)

The 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).

For user: using the `hop` plugin

To execute a build (or command execution), users must activate the hop plugin and configure its execution rules:

 1- url: /home/rmaneschi/projects/gitroot/app/testsuite/../plugins/hop/hop-0.0.1.wasm
 2  name: hop
 3  version: 0.0.1
 4  active: true
 5  run:
 6    - path: "*"
 7      branch:
 8        - "*"
 9      when:
10        - add
11        - mod
12      write:
13        git: []
14        web: []
15        exec:
16          - command: cat
17      configuration:
18        exec:
19          build: ""
20          cmds:
21            - args:
22                - README.md
23              cmd: cat
24          env: []

Add all desired commands for the plugin to call in run.write.exec.

Then in run.configuration.exec:

set environment variables via env (e.g., "MY_ENV=my_val")
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)
define the commands and arguments to execute under cmds

Plugin api report and reporter

Occasionally, 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.

Past 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.

To allow reporting without forcing a communication channel, I’ve created two new plugin APIs.

Report: 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.

Reporter API: after reports are collected, GitRoot calls all plugins that implement the Reporter interface.

Currently, 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!

GitRoot bets on mise

Managing 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.

This 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.

Communication and community building

Alongside the technical work for v0.3.0, a focused effort was put into non-technical tasks to improve communication with the community.

I also established a direct chat room on matrix, accessible via https://matrix.to/#/#gitroot:matrix.org. Feel free to stop by to ask questions or just say hello.

I’ve added a contact 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”!

Finally, I published a blog post titled “How to help building GitRoot 11-2025”. 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.

Apex a better web experience

The Apex plugin receives numerous bug fixes and quality of life improvements:

favicon support: a favicon can now be added via the configuration
styled 404 page: the 404 error page now correctly uses the site’s CSS
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
menu highlighting: the current page in the navigation menu is now highlighted
lightweight template: added some variables in header and footer templates

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.

And others useful updates

Although this article is already quite long, I want to briefly mention several smaller yet important tasks completed in this release.

ForgeConf update

The 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.

Integrated updater

I’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.

Rust and WASM

While 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.

0.2.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/09/18

Version 0.2.0 is here

In this version, my main focus was on stabilization. I fixed over 14 issues, some of which were identified before version 0.1.0, but a significant proportion were reported by YOU. A big thanks to everyone who took part of it in any way.

Every time I shared gitroot, I came across new issues with the documentation and binaries, but also questions such as “how can I compile it?” or “what’s the next step?”. And I’m delighted to see your enthusiasm for it!

First contribution

Although all my new contributions were related to “bug fixes”, some of them required new features.

No notification == no contribution

The first amusing problem came from the first contributor! Fifteen days later, he contacted me to say, “Hi, I pushed a branch where I corrected a lot of typos, but… nothing has happened since I pushed it?”. In fact, I wasn’t actually aware that a new branch had been pushed. I had forgotten to implement a mechanism that would notify me whenever a new contribution is published!

A simple way to achieve this is to add an RSS feed (yes, I was inspired by Radicle for this feature). This is ideal, because all I have to do is add an “rss.xml” file to the web folder…and the current API of plugin 0.1.0 allows me to do this! So I created the pollen plugin. It takes all the commits from all branches and adds an rss:item to a page.

However, in order to achieve this, I opted to experiment with a different programming language (all the plugins are developed in Golang). I chose assemblyscript, which is a subset of the typescript language. So I added a new plugin sdk in typescript.

To follow all gitroot commits follow https://gitroot.dev/rss/all-commits.xml

Lot of bugs

During this first contribution, I discovered numerous bugs in the “grafter” plugin. From the diff rendering to unwanted merging and very complicated final merging, nothing worked! Even the basic GitRoot features were painful to use :D

Let’s the show continue

No linux == no gitroot

Surprisingly, someone wanted to compile gitroot on a Mac. Well, gitroot is actually written in Go, so there’s no problem doing that… Except that I forgot to publish a fix I made to a dependency. Go couldn’t download the right dependency and therefore fails to compile completely… But everything is OK now! I added an automatic compilation for Mac, you can find this on the version page.

Doc, doc… doc?

After that, someone tried to run gitroot on their local computer, as described in the document. However, when version 0.1.0 was released, I discovered a bug. Gitroot cannot know where the root repository is located (because you can change its name). To fix this, I added a configuration file before initialization, which had to be passed on launch… It’s my fault, I forgot to update this tutorial.

A lot more

As you can see, there were many mistakes in the first version. However, they have all been fixed, and, of course, I have added plenty more to keep me busy for the next version!

More technicals bugs

But I also fixed several important issues that were the result of some shortcuts that every project has to take for publication. One was about a FS bug when directories were empty, another concerned the garbage collect plugin when the plugin had finished running, and many others.

Simplify plugin install

In the 0.1.0 version, to install a plugin you should download it, tell to gitroot where it is and then after push/pull activate/configure it. Now it is way more simple, just give an url, like https://gitroot.dev/releases/0.2.0/pollen-0.0.1.wasm and optionnally (but encouraged) a checksum sha256: 49cd8e1846b1612a0d5686918b502fe29e070e7bf9613c1ba9a1dfe5417d0f2a. Gitroot will download, check and run it. Of course you need to activate it. All url and checksum are in the versions page.

I have added a mecanisme to check that the plugin you try to run is compatble with your version of GitRoot. So launching ladybug-0.0.1.wasm in gitroot-0.2.0 will log an error and not run the wasm. As GitRoot is in alpha version all new gitroot version will need plugins update.

What next?

With the exception of any new bugs detected for the next iteration, I would like to focus on the following:

creating a plugins marketplace
adding a new language SDK for plugins (Maybe Rust? Or Zig?)
rebasing the Git lib fork and applying patches

0.1.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/09/18

GitRoot 0.1.0 is deployed 🎉��

GitRoot in numbers:

58 commits
+500 files https://gitroot.dev/worktree/
1 issue in gitlab (closed) https://gitlab.com/gitroot/gitroot/-/issues/1
29 issues close https://gitroot.dev/boards/closed.html
43 issues open https://gitroot.dev/boards/issues.html
22 pages de doc https://gitroot.dev/doc/
4 licences https://gitroot.dev/README.html#license
4 plugins https://gitroot.dev/CHANGELOG.html#plugins

But if you retain only one, it is:

1 contributor https://gitroot.dev/worktree/.gitroot/users.yml.html (others are forge and plugins 😭)

So there is only one thig to do… read the doc and contribute!

blog/security-vulnerability-1.md

rmaneschi@gmail.com (Romain Maneschi) — 2026/03/30

Security Advisory: Executor Command Injection

1. Executive Summary

A vulnerability has been identified within the GitRoot executors system. Under specific conditions, it is possible for a malicious actor to execute unauthorized commands on the host machine. Given the complexity of the required conditions, this vulnerability is not easily exploitable in a standard production environment.

Severity: Moderate
Affected Version: 0.3.0
Fix Status: Scheduled for version 0.4.0

2. Technical Details

The vulnerability stems from the way executors validate commands defined by plugins. Currently, a plugin can declare a benign command in its manifest (e.g., cat), but execute an arbitrary command during runtime (e.g., rm -rf data/). GitRoot currently lacks a strict enforcement mechanism to verify that the executed binary matches the declared command.

3. Impact Analysis

The level of risk depends on your infrastructure configuration:

High Risk: Users utilizing bareMetal or ssh executors.
Low Risk: Users utilizing bubblewrap or container isolation (as the sandbox significantly limits the potential impact on the host).

Exploitability Constraints: This vulnerability is not a “remote code execution” flaw in the traditional sense. Exploitation requires:

Installing a malicious plugin.
Having write access to the default branch of the root repository.
Merging a malicious .gitroot/plugins.yml into the default branch.

Currently, creating plugins is undocumented, and the only known plugin using executors is hop. Since any modification to .gitroot/plugins.yml requires a merge into the default branch, a standard code review process should easily detect and prevent such malicious entries.

4. Immediate Mitigations

If you cannot wait for the 0.4.0 release, we recommend applying the following measures:

Disable Executors: Set your forge configuration for executors to None.
Secure Executors: Use more secure executors, such as bwrap or container.
Plugin Trust: Only install and enable plugins from trusted sources.
Access Control: Strictly monitor and review all changes to .gitroot/plugins.yml, specifically focusing on authorized system commands.

5. Patch Schedule

This vulnerability will be fully addressed in version 0.4.0. We have decided not to release an intermediate 0.3.1 patch, as the attack vector relies on an “insider” or “compromised account” scenario that is effectively mitigated by standard code review practices.

6. Security Contact

Transparency and security are core values at GitRoot. If you discover any other potential vulnerabilities or have questions regarding this report, please contact us directly at contact@gitroot.dev.

Modifying the API in the SDK Plugin

rmaneschi@gmail.com (Romain Maneschi) — 2026/04/06

Modifying the API in the SDK Plugin

The last feature for version 0.4 is about adding mv (move) and cp (copy) functions to the SDK plugin. I’m taking advantage of this development to explain how the plumbing works under the hood.

Right now, the SDK plugin is undocumented because there are a lot of breaking changes coming. Every time I develop a new plugin, I discover better ways to do things, and the SDK needs to adapt.

For example, when I added apex_code (a plugin that takes code as a string and returns syntax-highlighted HTML), I wondered: “Is this a standalone plugin?”. Not really, because there’s no file to manipulate, neither in input nor output. Instead, it manages blocks inside an existing file. The SDK wasn’t originally built with that use case in mind.

Anyway, I think explaining how the SDK works through a concrete example will be helpful, if not for you, at least for me.

What is the SDK’s job?

The SDK exists to pass data from GitRoot (the host) to the plugin (the guest). As you know, GitRoot uses WebAssembly (WASM) to manage plugins. Unfortunately, WASM is still a bit low-level to implement: between the host and the guest, only integers can travel.

Wait, only integers?

Yes. So, how do we send a string? The host can store any kind of data in the guest’s memory. GitRoot stores a string, retrieves the pointer (the memory address) and the size, and sends those two integers to the guest. The guest then retrieves the string from its own memory. It’s a complex dance just for a simple string. The SDK is here to hide all that mess.

When you build a plugin, you just implement an interface. The SDK handles the rest: you receive objects and strings, and you send back data without ever worrying about the underlying WASM pointers.

What does a concrete implementation look like?

When I add a new function, I always start with the host side. All functions are located in runtime.go.

We need to register the function in wazero, our WASM runtime. I add two versions because I haven’t found a clean way to bridge the difference between AssemblyScript and Go/Rust yet. Hopefully, I’ll figure that out one day.

1r.wazRun.
2    NewFunctionBuilder().WithFunc(r.MoveFileBuilder(false)).Export("moveFile").
3    NewFunctionBuilder().WithFunc(r.MoveFileBuilder(true)).Export("moveFileAS")

Then I implement the builder:

 1func (r *runtime) MoveFileBuilder(forAS bool) interface{} {
 2	if !forAS {
 3		return func(_ context.Context, m api.Module, ptr, size, ptr2, size2 uint32) {
 4			// from ptr/size to string or object
 5			r.moveFile(fromPath, toPath)
 6		}
 7	} else {
 8		return func(_ context.Context, m api.Module, ptr, ptr2 uint32) {
 9			// from ptr to string or object
10			r.moveFile(fromPath, toPath)
11		}
12	}
13}

Yeah, I know. As a Gopher, seeing interface{} as a return type and all these uint32 feels wrong. But hey, we’re not here for a code review, we’re here to add an API. If you have a cleaner way, feel free to submit a graft!

We want to allow any plugin to move a file. Let’s define the internal moveFile function:

1func (r *runtime) moveFile(fromPath, toPath string) error {
2	//need to do something...
3}

Actually, there’s a catch, GitRoot uses three internal filesystems: one for the git worktree, one for web content, and one for the cache. Even if they are abstracted under one root, the code often expects a specific FS. I’ll probably clean this up later, but for now:

1func (r *runtime) moveFile(fromFs, fromPath, toFs, toPath string) error {
2	//need to do something...
3}

Now your plugin can call moveFile("cache", "artifacts/myBin", "web", "releases/myBin-v1.0") to publish an artifact, or moveFile("web", "index.html", "web", "old/index.html") to back up a file.

I won’t bore you with the implementation logic here. If you’re curious, check the code.

Here is how the final builder looks, converting pointers to strings:

 1func (r *runtime) MoveFileBuilder(forAS bool) interface{} {
 2	if !forAS {
 3		return func(_ context.Context, m api.Module, fromFsPtr, fromFsSize, fromPathPtr, fromGlobPathSize, toFsPtr, toFsSize, toPathPtr, toPathSize uint32) uint64 {
 4			fromFs, err := r.readString(m, "MoveFile fromFs", fromFsPtr, fromFsSize)
 5			if err != nil {
 6				return r.sendEmptyOrError(m, err)
 7			}
 8			fromPath, err := r.readString(m, "MoveFile fromGlobPath", fromPathPtr, fromGlobPathSize)
 9			if err != nil {
10				return r.sendEmptyOrError(m, err)
11			}
12			toFs, err := r.readString(m, "MoveFile toFs", toFsPtr, toFsSize)
13			if err != nil {
14				return r.sendEmptyOrError(m, err)
15			}
16			toPath, err := r.readString(m, "MoveFile toPath", toPathPtr, toPathSize)
17			if err != nil {
18				return r.sendEmptyOrError(m, err)
19			}
20			return r.sendEmptyOrError(m, r.moveFile(fromFs, fromPath, toFs, toPath))
21		}
22	} else {
23		return func(_ context.Context, m api.Module, fromFsPtr, fromPathPtr, toFsPtr, toPathPtr uint32) uint64 {
24			fromFs, err := r.readASString(m, "MoveFileAS fromFs", fromFsPtr)
25			if err != nil {
26				return r.sendEmptyOrError(m, err)
27			}
28			fromPath, err := r.readASString(m, "MoveFileAS fromGlobPath", fromPathPtr)
29			if err != nil {
30				return r.sendEmptyOrError(m, err)
31			}
32			toFs, err := r.readASString(m, "MoveFileAS toFs", toFsPtr)
33			if err != nil {
34				return r.sendEmptyOrError(m, err)
35			}
36			toPath, err := r.readASString(m, "MoveFileAS toPath", toPathPtr)
37			if err != nil {
38				return r.sendEmptyOrError(m, err)
39			}
40			return r.sendEmptyOrError(m, r.moveFile(fromFs, fromPath, toFs, toPath))
41		}
42	}
43}

When I need to pass complex objects, I use json.Marshal in GitRoot and json.Unmarshal in the SDK. It works, but don’t get too attached to it, I might change the serialization method in the future.

Inside the SDK

Now that the host is ready, we need to implement the other side: the SDK itself. I usually start with Go, then move to Rust and AssemblyScript. Sometimes I forget the others… shame on me! I’m planning to automate this with some boilerplate generation later.

In the server interface:

1type Server interface {
2    //...
3    MoveFile(fromFs, fromPath, toFs, toPath string) error
4    //...
5}

To make it more “user-friendly”, I use a struct to represent the filesystem in model/fs.go:

1func (g *GrFs) MoveFile(fromPath string, toPath string) error {
2    return g.server.MoveFile(g.base, fromPath, g.base, toPath)
3}
4
5func (g *GrFs) MoveFileToFs(fromPath string, toFs *GrFs, toPath string) error {
6    return g.server.MoveFile(g.base, fromPath, toFs.base, toPath)
7}

The actual WASM call happens in plugin/server.go, where we transform strings back into pointers:

 1// MoveFile implements [model.ServerNeeded].
 2func (s *pServer) MoveFile(fromFs model.FsBase, fromPath string, toFs model.FsBase, toPath string) error {
 3	ptr, size := stringToPtr(string(fromFs))
 4	ptr2, size2 := stringToPtr(fromPath)
 5	ptr3, size3 := stringToPtr(string(toFs))
 6	ptr4, size4 := stringToPtr(toPath)
 7	resPtrSize := _moveFile(ptr, size, ptr2, size2, ptr3, size3, ptr4, size4)
 8	runtime.KeepAlive(fromFs)
 9	runtime.KeepAlive(fromPath)
10	runtime.KeepAlive(toFs)
11	runtime.KeepAlive(toPath)
12	return ptrSizeToError(resPtrSize)
13}

And finally, the link to the host via go:wasmimport in plugin/imports.go:

1//go:wasmimport gitroot moveFile
2func _moveFile(fromFsPtr, fromFsSize, fromPathPtr, fromPathSize, toFsPtr, toFsSize, toPathPtr, toPathSize uint32) (ptrSize uint64)

How to use it?

Now, any plugin can use this. Here’s a simple Go plugin that triggers a build whenever a .go file is modified and moves the binary to the web folder.

 1package main
 2
 3import (
 4	"fmt"
 5	"path/filepath"
 6	"strings"
 7
 8	gitroot "gitroot.dev/libs/golang/plugin"
 9	"gitroot.dev/libs/golang/plugin/model"
10)
11
12var defaultRun = []model.PluginRun{{
13	Path:   "**/*.go",
14	When:   model.PluginRunWhenAll,
15	Branch: []string{"main"},
16	Write: model.PluginWrite{
17		Web: []model.PluginWriteRight{{
18			Path: "releases/main",
19			Can:  model.PluginWriteRightCanAll,
20		}},
21	},
22}}
23
24type Plugin struct {
25	server model.Server
26    needToBuild bool
27}
28
29func (p *Plugin) Init(repoName string, confHasChanged bool, serializedConf string) error {
30    p.needToBuild = false
31    return nil
32}
33
34func (p *Plugin) StartCommit(commit model.Commit) error                                  { return nil }
35
36func (p *Plugin) AddFile(file model.File) error                                          {
37	p.needToBuild = true
38    return nil
39}
40
41func (p *Plugin) ModFile(file model.File) error                                          {
42	p.needToBuild = true
43    return nil
44}
45
46func (p *Plugin) DelFile(file model.File) error                                          {
47	p.needToBuild = true
48    return nil
49}
50
51func (p *Plugin) EndCommit(commit model.Commit) error                                    { return nil }
52
53func (p *Plugin) Finish() error                                                          {
54    if p.needToBuild {
55        res, _ := p.server.Exec(model.Exec{
56            Cmds: []model.Cmd{
57                {Cmd: "go", Args: []string{"build"}},
58            },
59            Artifacts: []string{"main"},
60        })
61        return p.server.Cache().MoveFileToFs(res.Artifacts[0], p.server.Webcontent(), filepath.Join("releases", "main"))
62	}
63    return nil
64}
65
66func Build(server model.Server) model.Plugin {
67	return &Plugin{
68		server: server,
69	}
70}
71
72//go:wasmexport install
73func main() {
74	gitroot.Register(defaultRun, Build)
75}

Is that all?

Nope. I still need to update the Rust and AssemblyScript SDKs and, of course, add tests. But this should give you a good idea of how the plumbing works.

If anything is unclear, let me know!

Comment contribuer au développement de GitRoot

rmaneschi@gmail.com (Romain Maneschi) — 2025/11/18

Comment contribuer au développement de GitRoot 11-2025

Je viens tout juste de lire cette article et je n’arrête pas d’y penser. Je le met en perspective des contributeurs de GitRoot. Je suis le seul contributeur (à part mon ami Damien qui a corrigé de nombreuses fautes, merci à lui) sur ce projet. Et comme le montre ce toot j’ai un travail pour payer les factures, 1 femme et 2 enfants qui m’occupent pratiquement tout le reste du temps. À ça je rajoute GitRoot, pour le moment je m’éclate et je tiens bon mais pour combien de temps je vais y arriver ?

Alors pourquoi pas de contributeurs externes sur GitRoot ?

Je me dit souvent que le projet est jeune, trop jeune, pour que ça soit accessible à un developpeur externe. Parfois je me dit qu’un meilleurs système de ticket serait nécessaire pour avoir un label “welcome new contribution”. Parfois je me dit qu’une fois que j’aurais déployé les plugins sdk et fait un market place de plugins, enfin vous pourrez venir m’aider à faire que GitRoot soit un vrai projet open-source.

Mais, car il y a un mais, cette liste ne s’arrêtera jamais. Soyons franc il y aura toujours un truc de plus à faire avant que vous puissiez m’aider à faire que GitRoot soit au top. J’ai donc décidé de faire la chose la plus simple à l’heure actuelle pour vous expliquer comment m’aider: un article de blog.

Ici, je vais vous expliquer tout ce qu’il est possible de faire en l’état actuel du projet. Pas ce qu’il sera possible de faire un jour peu être, mais ce que vous pouvez faire là maintenant. Je réitèrerais ce genre d’article tant que nécessaire.

Pré-requis

Il n’y a pas grand chose à faire pour être prêt à aider sur GitRoot:

vous devez avoir git
git clone ssh://gitroot.dev
cd gitroot.dev
./gitroot/init.sh

Si vous souhaitez coder il vous faudra en plus:

bash et make (si vous êtes dev il y a de grandes chances que vous les aillez déjà)
installer mise, c’est le plus simple pour avoir tous les compilateurs dans les bonnes versions

Et voila vous êtes bon pour commencer à aider. Mais que faire ? Et bien comme tout bon developpeur je vais vous répondre “ça dépend”. Ça dépend de ce que vous voulez faire ! Je vais lister dessous un ensemble de taches possibles, vous choisissez.

Avant de commencer

Avant de vous dire ce que vous pouvez faire, je me dit qu’il serait bien de vous expliquer ce que moi je fais. Donc pour cette version 0.3.0 ma priorité absolue est de faire en sorte que GitRoot build GitRoot lui même. Aujourd’hui à chaque release je fais les binaires sur ma macine et je les scp. Je veux qu’avec cette version 0.3.0 cela ne soit plus le cas.

Donc, si j’arrive à me retenir, je ne devrais pas faire les tickets qui suivent. Vous avez tout le temps dont vous souhaitez pour les faire. Le plus simple est, je pense, de nous retrouver sur matrix channel gitroot pour en discutter.

On peut également en parler par mail contact@gitroot.dev ou sur le fediverse ^{[forge@gitrrot.dev]}(https://gts.gitroot.dev/@forge).

Qu’est-ce qu’on peut faire ?

Corriger les fautes

L’anglais n’est pas ma langue d’origine et je pense qu’il y a beaucoup de fautes, donc une tache pourrais être de lire tous les md dans /doc/, /blog/ et pourquoi pas /issues/. Vous corrigez, faites une branche et poussez. Je m’occupe du reste !

Moi je veux faire du web

Ce qui serait top, ce serait de créer (ou de trouver) un thème. Aujourd’hui GitRoot utilise simplecss, et il n’a besoin que de css classless, il en existe beaucoup mais vous pouvez aussi créer celui de GitRoot.

Le plus simple pour essayer est de lancer la commande make testsuite quand elle a fini rendez vous dans cd /tmp/repo1 éditez le fichier style.css puis git add . git commit -m "try style" et git push, ouvrez http://127.0.0.1:4546/repo1.

Quand vous êtes content faites une branche avec votre css dans apex, puis git add . et git push je m’occupe du reste.

Moi je veux coder

Bien, pas de soucis, voici une liste de petites tâches (enfin elles me paraissent petites mais si c’est pas le cas pour vous dites le moi):

en golang:
- dans le plugin grafter pouvoir afficher autre chose dans le 1er message d’un graft. La bannière est en dure dans le plugin, il faudrait l’exporter dans la conf du plugin et l’utiliser.
- dans le plugin silo permettre de grouper par fichier ou date
- plus difficile mais j’aimerais bien avoir plus de renderer dans apex, par exemple les infos, warning et autre
en typescript:
- dans le plugin pollen il y a un bug sur le rss il est jamais nettoyé. Rajouté une option (ou pas, 100 en dur me semble être déjà pas mal) pour limiter le nombre d’<item>.
- toujours dans le plugin pollen pourquoi pas rajouter un json feed en plus du rss. On peut serializer du json en assemblescript.
- plus difficile mais il serait bien de pouvoir dire au plugin pollen de générer un rss avec le contenu des fichiers. Ça permettrait à GitRoot d’avoir un rss affichant les articles du blog par exemple. Aujourd’hui il ne met dans le rss que les commits.
en rust:
- faire ce que Ygor à dit dans https://floss.social/@ygor/115474535138702961 je ne suis pas un developpeur rust et transformer des String en &str me parle pas beaucoup mais si vous l’êtes je suis sûr que c’est une petite tâche. Le code se trouve dans le plugin sdk et le plugin hop.
- ajouter un fakeServer au plugin sdk pour faciliter les tests d’un plugin, voici celui de go https://gitroot.dev/worktree/app/libs/golang/plugin/test/fakeserver.go.html

Moi je suis sysadmin

Parfait il y a de quoi faire aussi:

aujourd’hui il y a trop d’étapes pour releaser GitRoot, automatiser au maximum m’aiderais beaucoup.
si vous avez un petit de place sur un de vos serveurs, tester de déployer une instance juste pour le fun. Peu être vous pourrez améliorer la doc ou trouver quelque chose qui ne marche plus. Ou ajouter un paragraphe pour utiliser gitroot avec nginx ou autre.

Moi je veux tester

tous les tests sont en bash dans testsuite/runtest.sh se trouve le plus gros test, à côté il y en d’autres
- exécutez les pour voir s’ils marchent chez vous me parait une bonne première tâche
- en créer de nouveaux
- améliorer les existants en sortant par exemple des fonctions helper comme quiet_git(), report() ou mySleep() dans d’autres fichiers (et les importer) serait d’une grande aide pour le projet. Vous pouvez aussi créer des nouveaux pour killGitroot() qui est fait en début de chaque fichier. Ou createProject() qui consiste à chaque fois à aller dans le root repository et ajouter son nom dans le fichier .gitroot/repositories.yml.

Moi je veux juste réfléchir/discutter

Tu es le bienvenue sur le channel gitroot dans matrix. Ou par mail contact [AT] gitroot.dev ou sur le fediverse @forge@gitroot.dev sur ce serveur.

How to help building GitRoot

rmaneschi@gmail.com (Romain Maneschi) — 2025/11/18

How to help building GitRoot 11-2025

This article is the translation of french version thanks to DeepL

I just read this article and I can’t stop thinking about it. I’m putting it into perspective for GitRoot contributors. I’m the only contributor (apart from my friend Damien, who corrected numerous typos, thank you to him) on this project. And as this toot shows, I have a job to pay the bills, a wife and two children who take up practically all the rest of my time. On top of that, I have GitRoot. For now, I’m having a blast and hanging in there, but how long can I keep it up?

So why not have external contributors on GitRoot?

I often tell myself that the project is young, too young, to be accessible to an external developer. Sometimes I think that a better issues system would be necessary to have a “welcome new contribution” label. Sometimes I think that once I’ve deployed the SDK plugins and created a plugin marketplace, then you can come and help me make GitRoot a true open-source project.

But, because there is a but, this list will never end. Let’s be honest, there will always be something else to do before you can help me make GitRoot the best it can be. So I decided to do the simplest thing possible right now to explain how you can help me: a blog post.

Here, I’ll explain everything that can be done in the current state of the project. Not what might be possible someday, but what you can do right now. I’ll repeat this kind of article as often as necessary.

Prerequisites

There isn’t much you need to do to get ready to help out on GitRoot:

you need to have git
git clone ssh://gitroot.dev
cd gitroot.dev
./gitroot/init.sh

If you want to code, you will also need:

bash and make (if you are a developer, chances are you already have them)
Install mise, which is the easiest way to get all the right versions of the compilers

And now you’re ready to start helping. But what should you do? Well, like any good developer, I’ll answer, “It depends.”. It depends on what you want to do! I’ll list a set of possible tasks below, and you can choose.

Before we begin

Before telling you what you can do, I thought it would be a good idea to explain what I am doing. So, for this version 0.3.0, my top priority is to make sure that GitRoot builds GitRoot itself. Currently, for each release, I build the binaries on my machine and then scp them. I want this to no longer be the case with version 0.3.0.

So, if I can restrain myself, I shouldn’t have to do the following tickets. You have all the time you need to do them. The easiest thing, I think, is to meet up on matrix channel gitroot to discuss them.

We can also talk about it by email contact@gitroot.dev or on the fediverse ^{[forge@gitrrot.dev]}(https://gts.gitroot.dev/@forge).

What can we do?

Correct mistakes

English is not my native language, and I think there are a lot of typos, so one task could be to read all the MD files in /doc/, /blog/, and maybe even /issues/. Correct them, create a branch, and push. I’ll take care of the rest!

I want to work on the web

It would be great to create (or find) a theme. GitRoot currently uses simplecss, and it only needs classless CSS. There are many available, but you can also create one for GitRoot.

The easiest way to try it out is to run the make testsuite command. When it’s finished, go to cd /tmp/repo1, edit the style.css file, then git add . git commit -m "try style" and git push. Open http://127.0.0.1:4546/repo1.

When you are satisfied, create a branch with your CSS in apex, then git add . and git push. I’ll take care of the rest.

I want to code

Okay, no worries, here’s a list of small tasks (well, they seem small to me, but if that’s not the case for you, let me know):

in golang:
- in the grafter plugin, be able to display something else in the first message of a graft. The banner is hard-coded in the plugin; it would need to be exported to the plugin configuration and used.
- In the silo plugin, allow grouping by file or date
- More difficult, but I would like to have more renderers in apex, for example info, warnings, and others
in typescript:
- in the pollen plugin there is a bug in the RSS feed it is never cleaned up. Added an option (or not, 100 seems fine to me) to limit the number of <item>.
- Still in the pollen plugin, why not add a json feed in addition to the RSS feed? We can serialize json in assemblescript.
- More difficult, but it would be nice to be able to tell the pollen plugin to generate an RSS feed with the contents of the files. This would allow GitRoot to have an RSS feed displaying blog articles, for example. Currently, it only puts commits in the RSS feed.
in Rust:
- Do what Ygor said in https://floss.social/@ygor/115474535138702961 I’m not a Rust developer and converting String to &str doesn’t mean much to me, but if you are, I’m sure it’s a small task. The code can be found in the plugin sdk and the hop plugin.
- Add a fakeServer to the plugin sdk to facilitate plugin testing. Here is the one for Go https://gitroot.dev/worktree/app/libs/golang/plugin/test/fakeserver.go.html

I’m a sysadmin.

Perfect, there’s plenty to do:

Today, there are too many steps to release GitRoot. Automating as much as possible would help me a lot.
If you have a little space on one of your servers, try deploying an instance just for fun. Maybe you can improve the documentation or find something that no longer works. Or add a paragraph on using gitroot with nginx or something else.

I want to test

All tests are in bash in /app/testsuite/. The largest test is located in runtest.sh, along with others.
- Running them to see if they work on your system seems like a good first task to me.
- Creating new ones
- Improving existing ones by, for example, moving helper functions such as quiet_git(), report(), or mySleep() to other files (and importing them) would be a great help to the project. You can also create new ones for killGitroot(), which is done at the beginning of each file. Or createProject(), which consists of going to the root repository each time and adding its name to the .gitroot/repositories.yml file

I just want to think/discuss

You are welcome to join the gitroot channel on Matrix. Or contact us by email at contact [AT] gitroot.dev or on the Fediverse at @forge@gitroot.dev on this server.

Issues, Tickets, Discussions... Call them what you want!

rmaneschi@gmail.com (Romain Maneschi) — 2026/06/08

Issues, Tickets, Discussions… Call them what you want!

Many of you, when checking out https://gitroot.dev, have told me that the 🐞 Issues button shouldn’t be labeled “Issues”, but rather “Tickets” or “Discussions”.

First of all, thanks for the feedback! I really appreciate it, that’s how I can build a better forge. Of course, I will change the label, but developing a forge means having a lot of different areas to work on: issues/boards, git, code, CI/CD, and with GitRoot, even more, like plugins and WASM…

So, why don’t I just change this label right away? In reality, this label isn’t hardcoded inside GitRoot. It’s only there because I configured plugins to display it. I want to take this opportunity to explain how GitRoot works, because the platform is developed around this exact concept: how to customize a forge at the project level.

The Original Idea

Imagine you are developing a forge, and to avoid vendor lock-in, you decide not to put anything outside of Git. You choose not to use any database at all. In this context, how do you design an “issue” system?

In traditional forges, an “issue” consists of a title and a description created by a user. We can represent it like this:

Easy, right? Well, how do you represent that in GitRoot using only files? This question was running through my mind for months before I finally found a solution.

The Basic Solution

Since I only have files at my disposal, what actually constitutes an “issue”? I need to add some metadata to a file so the system understands that this file is an issue and not, say, a main.go. I’ll probably want to group all these “issues” into a specific directory, because while GitRoot technically lets you do whatever you want (even dropping an issue right in the middle of your source code), I personally prefer to keep my files organized!

A simple text format that handles metadata perfectly is Markdown. I use Markdown here, but any other markup language could work. Let’s create a file named issues/1.md:

1---
2id: 1
3user: email@email.com
4status: OPEN
5---
6
7# My title
8
9My description where I can detail what my problem is.

Yes, it really is that simple. In GitRoot, to create an issue, you just create a file, add some metadata, commit, and push. Boom, you have an issue.

Now, you might be thinking: “Well, I lose a lot of control with that, the status could be anything!” or “How are other users supposed to know what to put where?”. You’re right, and that is exactly where plugins enter the game.

A Better Solution

If I simplify this as much as possible, what does an external contributor actually need to provide to create an issue? Just a title and a description. So, let’s create a file named issues/my_issue.md:

1# My title
2
3My description where I can detail what my problem is.

Then, we run git commit && git push. Since I have configured the ladybug plugin like this:

 1- name: ladybug
 2  ...
 3  - path: issues/**/*.md
 4    branch:
 5    - "*"
 6    when:
 7    - add
 8    - mod
 9    func: []
10    write:
11      git:
12      - path: issues/**/*.md
13        can:
14        - mod
15      web: []
16      exec: []
17      callfunc: []
18    configuration:
19      metadata:
20      - default: autogenerated
21        mandatory: true
22        name: id
23        type: crc16
24      - default: OPEN
25        mandatory: true
26        name: status
27        type: string
28      - default: email@email.com
29        mandatory: false
30        name: user
31        type: string

You can read this configuration as: “For every Markdown file in the issues directory across all branches, if the file doesn’t have these metadata fields, automatically add these default values.”

Now, if you are a Git purist, a server creating commits right on top of yours might sound a bit radical, or even terrifying. But look closely at the write block in the YAML configuration above:

1write:
2  git:
3    - path: issues/**/*.md
4      can:
5        - mod

GitRoot doesn’t just let plugins run wild, the project configuration must explicitly grant the plugin permission to write or modify files on specific paths. If you don’t declare these rights, GitRoot will block the plugin from making any changes.

When granted, GitRoot intercepts your push, lets the plugin inject the missing metadata, and safely generates a follow-up commit. And don’t worry about your history: if you decide to git rebase -i later to squash or fixup your commits, plugins won’t generate duplicate commits if no metadata has changed.

What about security or external users trying to forge metadata? Since contributors cannot push directly to the default branch (like main), they have to go through a branch and need to be merged. This means every single change to an issue’s status or metadata is subjected to a code review.

If an external user tries to close someone else’s issue or manipulate IDs, it will stand out like a sore thumb in the git diff. Maintainers retain absolute control and can simply reject the rogue contribution. Security doesn’t rely on complex database permission tables, but on the battle-tested git review workflow you already know and trust.

So, once you push, the server-side plugin does its job, and the next time you run git pull, your local file will automatically look like this:

1---
2id: 1
3user: email@email.com
4status: OPEN
5---
6
7# My title
8
9My description where I can detail what my problem is.

Bingo! You get the exact same file, with the exact same metadata you wanted. Of course, a lot more needs to be added, like defining a type: user to assign an issue, or perhaps a type: status to define an enum of allowed values. But I think you see where I’m going with this feature!

(Note: If you’re wondering about the barrier to entry for non-technical contributors, my long-term vision is to allow plugins to intercept standard HTTP requests. Tomorrow, a classic web form will be able to POST to GitRoot and automatically commit a .md file under the hood. But for now, we are proudly dev-centric!)

So, What About the Label?

Throughout all of this, you’ll notice that the term “issue” only appears within the plugins themselves. Nowhere have we talked about that 🐞 Issues button yet. We actually need to introduce another plugin before we can tackle that topic.

First, we need a file that lists all of these “issues”. That’s exactly why the silo plugin exists. It inspects all files and groups them whenever it finds a matching pattern.

To list all open “issues”, we configure it like this:

 1- name: silo
 2  ...
 3  run:
 4  - path: "**/*"
 5    branch:
 6    - main
 7    when:
 8    - add
 9    - mod
10    - del
11    func: []
12    write:
13      git:
14      - path: boards/*.md
15        can:
16        - add
17        - mod
18        - del
19        - append
20      web: []
21      exec: []
22      callfunc: []
23    configuration:
24      boards:
25        description: All open issues
26        for: issues/*.md
27        format: table
28        paginator: 50
29        selects:
30        - "status: (.*)"
31        - "user: (.*)"
32        sort: select[0]
33        sortOrder: desc
34        tableHeader: "| | status | user |"
35        title: All issues
36        to: boards/issues.md
37        where: "status: OPEN"

You can read this configuration as: “For every file in the main branch, create a board called ‘All issues’ containing links to all files matching status: OPEN. Display them as a table with status and user columns.”

After running git commit && git push && git pull, you will get a new file at boards/issues.md containing something like this:

1# All issues
2
3All open issues
4
5|                                   | status | user            |
6| --------------------------------- | ------ | --------------- |
7| [My title](../issues/my_issue.md) | OPEN   | email@email.com |

Silo has aggregated all your open issues into a single dashboard. Of course, you could easily create another board for closed issues in a separate file like boards/closed.md, it’s entirely up to you.

(Note: If you are sweating at the thought of a plugin scanning your entire repository on every single push, don’t panic. silo, thanks to the plugin-sdk API, doesn’t do a full disk scan. It only processes the incremental diffs generated by the incoming commit. This is precisely why we restrict its scope to the main branch in this example.)

Now that we have a page representing all our issues, we can finally render it in the browser. Because, as you might have guessed, the label causing all this debate lives in the Web UI.

The Web is Where It Happens

To render my boards/issues.md file on the web, I use the apex plugin, in conjunction with the apex_markdown plugin, of course.

These plugins take files from git and render them directly in the Web UI. I configure them like this:

 1- name: apex
 2  ...
 3  run:
 4  - path: "**/*"
 5    branch:
 6    - main
 7    when:
 8    - add
 9    - mod
10    - del
11    func: []
12    write:
13      git:
14      - path: "**/*"
15        can:
16        - add
17        - mod
18        - del
19        - append
20      web:
21      - path: "**/*"
22        can:
23        - add
24        - mod
25        - del
26        - append
27      exec: []
28      callfunc:
29      - pluginname: apex_markdown
30        funcname: renderMd
31      ...
32    configuration:
33      ...
34      menu:
35      - display: 🏠 Home
36        link: /
37      - display: 📖 Documentation
38        link: /doc/
39      - display: 🔖 Versions
40        link: /CHANGELOG.html
41      - display: �� Plugins
42        link: /plugins/
43      - display: �� Issues
44        link: /boards/issues.html
45      - display: 🚀 Code
46        link: /worktree/
47      - display: ☕ Blog
48        link: /blog/
49      - display: �� Contact
50        link: /contact.html

Oh, do you see it now? Yes, right there: display: 🐞 Issues. This is the exact configuration that tells Apex to add a global menu item with the 🐞 Issues label, pointing to the /boards/issues.html file.

If you are wondering how Apex magically knows where to find your “issues”, the secret is: it doesn’t.

Apex isn’t a smart router, it’s just a file translator. It blindly takes the Markdown structure generated by GitRoot and renders it into HTML. Because I know Apex transforms boards/issues.md into boards/issues.html, I simply hardcode that target URL in my menu configuration (link: /boards/issues.html).

And what about the links inside the table? Apex has a clever built-in rewrite engine. When it parses your generated board file, it automatically rewrites every internal Markdown link, turning [My title](../issues/my_issue.md) into a standard web-friendly <a href="../issues/my_issue.html">. No database, no dynamic routing, just plain old static files mapped one-to-one.

Conclusion

If you change the label to 🐞 Tickets or 💡 Discussions, the “issue to rename issues into something else” can finally be closed. Ideally, you might also want to rename some directories in the other plugins’ configurations, but it’s really not a big deal.

I’m pretty sure you now understand why I didn’t immediately jump on resolving this task: everything we just saw is pure configuration, completely separated from the GitRoot core code.

And to be perfectly honest, I haven’t changed it yet because none of the traditional options really appeal to me. I don’t particularly like “Tickets” or “Discussions”, maybe it should be “Feature Requests” instead (and yes, you can now model that in GitRoot too!).

In fact, I personally call them TODOs, because in reality, they are all just waiting for me to get them done.

Wait… Why stop at issues?

This is where the true power of GitRoot will blow your mind.

Because GitRoot doesn’t care about databases, and because everything is just a file inside Git, the silo plugin can aggregate anything. I don’t need a separate TODO page for my tickets, because I already have one that automatically tracks the //TODO comments inside my actual source code.

Yes, you read that right. You can visit it live at https://gitroot.dev/boards/todos.html.

Every time I write a //TODO in a .go, .rs or .ts file, GitRoot parses it, aggregates it, and generates a dynamic dashboard. Tickets, documentation, source code comments… it’s all the exact same data structure.

To be clear, it doesn’t magically transform your source code comments into full-blown database-like issues with IDs and statuses. It simply extracts them to give you a centralized, living view of your technical debt, right alongside your official tickets. It’s the exact same data aggregation pipeline, tailored for two different use cases.

If you want to discover more plugins and configurations, feel free to browse through the 🧩 Plugins section. However, for now, the best way to explore remains checking out the actual GitRoot plugins.yml configuration file.

0.5.0 plugins

rmaneschi@gmail.com (Romain Maneschi) — 2026/10/30

What is GitRoot without its plugins?

But today, GitRoot and officials plugins are linked by the version. So let me explain what they can do in this new version.

All plugins are compatible with the 0.5.0

I’ll present here only the most important features, for details you can read the changelog of each plugin.

Firefly in zig

Silo, lots of new things

Silo: from files and metadata, Silo generates indexes to find files more easily. I have added a lot of features into this milestone.

You can now sort the rendered list by the files which each item links to. I use it to render all the TODOs in GitRoot, in the todo board.

Now Silo can render the list directly to the web. Useful to not encumber the git repositories with redundant lists. For example, I use it to render plugins in alphabetical order or by scope.

1- selects:
2    - "purl: pkg:gitroot/[^/]+/([^@]+)"
3    - "purl: pkg:gitroot/([^/]+)"
4  title: Plugins for scope $select[1]

This means that you select the scope and name of the PURL plugin and render the name into the title. A way to add metadata into the rendered list is to use the new metadata property.

The silo plugin use the standard regexp from go to extract selects.

To find examples on how to configure all of that, look at the silo configuration of gitroot.dev instance.

Apex is the web view

Following this strategy, the new slide layout renders the page with the slide.css and groups all page breaks into <section> as required by the CSS.

Another addition to apex_markdown is the ability to render callouts for blockquotes and details/summary. To render a callout, use this in your markdown:

1> [!NOTE]
2> This a note callout.

Which renders on the web as:

This a note callout.

Today, the possibilities are (but in the future I want to make them configurable):

1var calloutColor = map[string]string{
2	"[!NOTE]":    "#006ac7",
3	"[!WARNING]": "#be4700",
4	"[!ERROR]":   "#f00",
5}

Following the same philosophy, to render details/summary:

1> [!DETAILS] This is a summary
2> This is the details

Which renders on the web as:

This is a summary

This is the details

Finally, in a last-minute change before the release, I have added the metadata toc: true to be able to render a table of contents, because the v0.5.0 article was too long.

Grafter diff

Previously, Grafter displayed diffs only after the property status was set to review. But that was confusing. Now, from the start, it shows diffs.

And now that the Apex plugin can render summary/details, Grafter uses it to render reports from other plugins. You can see the result in the graft of this post.

Pollen render content

What next?

I have grouped multiple related issues in the apex board. That will be my priority, but of course, as I change my mind a lot, that’s not a promise of what will be done.

Special thanks to Ryuno-Ki from the #gitroot:matrix.org Matrix room for reviewing and correcting this article. Want to help with future posts? Join us in the room!

0.5.0

rmaneschi@gmail.com (Romain Maneschi) — 2026/10/05

Move slowly, and take care of things

Thanks to lonugem for the title idea

If you only have 5 minutes

Breaking PURL

Joking aside, you need to replace your plugin URL with a PURL one. ECMA PURL is a specification to produce “a standardized URL-based syntax that uniquely identifies software packages”.

This corresponds to the following change:

1- url: https://gitroot.dev/releases/0.4.0/ladybug-0.0.4.wasm
2- checksum: sha256:7409837469ce89d5c9fd8dd48236764650f48523ff4d81295967154977a01635
3- name: ladybug
4- version: 0.0.4
5+ purl: pkg:gitroot/gitroot/ladybug@0.0.5?checksum=sha256:afb22a26e7d489d72db0a2305d433a3c3ac2692959ba2412011c0d759b4c8518&registry=https:%2F%2Fgitroot.dev%2Freleases%2F0.5.0
6  active: true

Look in the plugins registry to find the exact purl for each plugin.

To know why, how and more read purl details.

A lot of people have discovered GitRoot

First show, first lobste.rs/HN links, first video… Yes, more and more people are talking about GitRoot. Discover where.

Not conclusive

Before it’s too late

My new favorite language…. until the next one

Plugins needs more power

Sftp to save the web

How many bugs?

A lot of bug fixes have been done. Let me explain some interesting ones.

In-depth Details

PURL breaking details

Another example is if someone forks ladybug and wants to release it in the registry. Previously there was no option to do that, so adding a scope seemed to be the best choice.

That was a big refactor to do, but I’m pretty happy with the result.

GitRoot communication

A lot has occured during this summer, on the communication side too.

And GitRoot has been added to AlternativeTo. I don’t know if this will lead to anything, but hey, I’m right alongside GitHub and GitLab :P

SdkGenerator full story

Max anonymous branches

Zig plugin-sdk

PluginSdk improvements

Regarding the plugin-sdk, here are a lot of new capabilities for plugins to use:

schedule: you can allow a plugin to be called at a scheduled time. The format is a cron expression with 5 segments as <minute> <hour> <day> <month> <weekday>. Example:

1- purl: pkg:gitroot/gitroot/firefly@0.0.1?checksum=sha256:fae956f5cc9239a87b1c2a149a5466fec85476377de4ada33dda190edb3700c4&registry=https:%2F%2Fgitroot.dev%2Freleases%2F0.5.0
2  active: true
3  run:
4    - path: ""
5      branch:
6        - main
7      when: []
8      schedule: "* * * * *"

That means the firefly plugin will be executed on the main branch every minute. Refer to the gronx library documentation for cron expression details.

1callFunc:
2  - pluginPURL: pkg:gitroot/gitroot/apex
3    funcName: renderHtml
4    configuration:
5      branchesDir: branches
6      favicon: logo.png
7      footer: <p>Start with <code>git clone ssh://gitroot.dev/</code> 🚀</p><small>Hosted with ❤️ by Gitroot</small>
8      generateGitWorktree: true
9      header: ...

Sftp feature

Be careful: this feature is in alpha, so don’t write scripts around it for now. I will probably change the directory hierarchy #d42a.

Some interesting bug fixes

What next?

Then I will probably start working on:

Discover GitRoot without installing anything.
Create your own plugins with ease.
Transform GitRoot into a registry for (at least) Go, Rust, NPM and Zig.
Federation with GitRoot but also other forges.
Implement something for users (how to represent them).
Manage more Git functions in plugins (branch, pull, push, rebase).
Use pull-iterators to stabilise the plugin-sdk.
Easier configuration of plugins.
Auto-update of plugins.
New language plugin-sdk.
Air-gapped version of GitRoot.
Make every repository a gemini capsule.

Special thanks to Ryuno-Ki, Matthieu and ks from the #gitroot:matrix.org Matrix room for reviewing and correcting this article. Want to help with future posts? Join us in the room!

0.4.0

rmaneschi@gmail.com (Romain Maneschi) — 2026/04/22

The teenager starts building its own future

If you only have 5 minutes

If you skim this article, don’t forget to check out the conclusion about “what’s next?”.

The thing i’m most proud of

Executors can finally build GitRoot! As I love to say: GitRoot can build GitRoot on GitRoot. And it was a pain to do. Read more.

The thing with the most visibility

The thing that changes everything but was so simple

The thing that was more complex than I thought

The things I’m just happy are done

No more mandatory signed commits! Well, it’s still better if you sign them, but this change means the .gitroot/init.sh has been ~~deleted~~ moved to a plugin. Read more.

In-depth Details

Executor

Still not the end! After that, I needed to configure port numbers, so I built a complete environment variable system, and used it to configure some mise paths.

But hey, let’s celebrate what we’ve built before jumping into the next sprint!

Plugin registry

Apex render branch

Elegant, but honestly, a total over-engineered mess. When I actually sat down to code this, I ended up adding just two lines to the apex plugin:

1if p.currentCommit.Branch != "" && p.currentCommit.Branch != p.config.defaultBranch {
2	path = filepath.Join(p.config.branchesDir, p.currentCommit.Branch, path)
3}

Plugin deps

So, I started building the apex_markdown plugin, then apex_code, and next week apex_mermaid. But what I hadn’t fully anticipated was the sheer amount of work required to make it all work together.

With this in place, I’m not even sure if I’ll keep the report system, which was an other way of passing information between plugins.

Sigma plugin

Now, you have the choice to accept unsigned commits in your repo. You can even ignore the whole signing topic entirely if you don’t install the stigma plugin.

That said, I’m still convinced that signing commits should remain the default.

FS plugin-sdk

I have marked all old methods as deprecated, and they will be removed in the next version of GitRoot (or more specifically, the plugin-sdk, though they share the same release number for now).

What next?

I have a massive roadmap for GitRoot (in no particular order):

Discover GitRoot without installing anything.
Create your own plugins with ease.
Transform GitRoot into a registry for (at least) Go, Rust, and NPM.
Plugins should be usable via PURL.
Plugins can send/receive HTTP requests.
Plugins can be scheduled.
Rebase go-git to take advantage of their performance improvements.
Generate the plugin SDK automatically.
Add plugin SDKs for (at least) Zig, Kotlin, and Python.

This is only the beginning. GitRoot will get better and better with every release.

0.3.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/12/20

From “baby to teenager” GitRoot become a forge

If you only have 5 minutes

To activate this new capability on your instance, follow the administrator section. To start using it as a user, see the user section.

Finally, I discuss Apex and many other tiny but useful things.

In-depth Details

For admin: activating an executor

When you update GitRoot to 0.3.0 a new configuration block will appear in the .gitroot/forgeConfig.yml file of your root repository:

 1execconf:
 2  baremetal:
 3    enabled: false
 4  bwrap:
 5    enabled: false
 6    user: nobody
 7    uid: 65534
 8    gid: 65534
 9    robind: []
10    bind: []
11  container:
12    enabled: false
13    bin: podman
14  ssh:
15    enabled: false
16    hosts:
17      - user: myUSer
18        address: 127.0.0.1
19        port: 22
20        publickey: ssh-ed25519 AAAAC3NzaC1...

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.

Bare Metal: simplest but most dangerous

Bubblewrap (bwrap): lightweight sandboxing

Container: heavyweight but most flexible

GitRoot 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.

SSH: remote execution (alpha)

For user: using the `hop` plugin

To execute a build (or command execution), users must activate the hop plugin and configure its execution rules:

 1- url: /home/rmaneschi/projects/gitroot/app/testsuite/../plugins/hop/hop-0.0.1.wasm
 2  name: hop
 3  version: 0.0.1
 4  active: true
 5  run:
 6    - path: "*"
 7      branch:
 8        - "*"
 9      when:
10        - add
11        - mod
12      write:
13        git: []
14        web: []
15        exec:
16          - command: cat
17      configuration:
18        exec:
19          build: ""
20          cmds:
21            - args:
22                - README.md
23              cmd: cat
24          env: []

Add all desired commands for the plugin to call in run.write.exec.

Then in run.configuration.exec:

set environment variables via env (e.g., "MY_ENV=my_val")
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)
define the commands and arguments to execute under cmds

Plugin api report and reporter

To allow reporting without forcing a communication channel, I’ve created two new plugin APIs.

Report: 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.

Reporter API: after reports are collected, GitRoot calls all plugins that implement the Reporter interface.

GitRoot bets on mise

Communication and community building

Alongside the technical work for v0.3.0, a focused effort was put into non-technical tasks to improve communication with the community.

To allow you to follow daily progress and current thoughts, I have set up a GoToSocial (Mastodon) instance. You can find the official account at @forge@gitroot.dev or directly at [https://gts.githe parameter�shaddr(default valuessh://localhost:4545/) andexternalhttpaddr(default valuehttp://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.

Integrated updater

Rust and WASM

0.2.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/09/18

Version 0.2.0 is here

First contribution

Although all my new contributions were related to “bug fixes”, some of them required new features.

No notification == no contribution

To follow all gitroot commits follow https://gitroot.dev/rss/all-commits.xml

Lot of bugs

Let’s the show continue

No linux == no gitroot

Doc, doc… doc?

A lot more

As you can see, there were many mistakes in the first version. However, they have all been fixed, and, of course, I have added plenty more to keep me busy for the next version!

More technicals bugs

Simplify plugin install

What next?

With the exception of any new bugs detected for the next iteration, I would like to focus on the following:

creating a plugins marketplace
adding a new language SDK for plugins (Maybe Rust? Or Zig?)
rebasing the Git lib fork and applying patches

0.1.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/09/18

GitRoot 0.1.0 is deployed 🎉��

GitRoot in numbers:

58 commits
+500 files https://gitroot.dev/worktree/
1 issue in gitlab (closed) https://gitlab.com/gitroot/gitroot/-/issues/1
29 issues close https://gitroot.dev/boards/closed.html
43 issues open https://gitroot.dev/boards/issues.html
22 pages de doc https://gitroot.dev/doc/
4 licences https://gitroot.dev/README.html#license
4 plugins https://gitroot.dev/CHANGELOG.html#plugins

But if you retain only one, it is:

1 contributor https://gitroot.dev/worktree/.gitroot/users.yml.html (others are forge and plugins 😭)

So there is only one thig to do… read the doc and contribute!

blog/security-vulnerability-1.md

rmaneschi@gmail.com (Romain Maneschi) — 2026/03/30

Security Advisory: Executor Command Injection

1. Executive Summary

Severity: Moderate
Affected Version: 0.3.0
Fix Status: Scheduled for version 0.4.0

2. Technical Details

3. Impact Analysis

The level of risk depends on your infrastructure configuration:

High Risk: Users utilizing bareMetal or ssh executors.
Low Risk: Users utilizing bubblewrap or container isolation (as the sandbox significantly limits the potential impact on the host).

Exploitability Constraints: This vulnerability is not a “remote code execution” flaw in the traditional sense. Exploitation requires:

Installing a malicious plugin.
Having write access to the default branch of the root repository.
Merging a malicious .gitroot/plugins.yml into the default branch.

4. Immediate Mitigations

If you cannot wait for the 0.4.0 release, we recommend applying the following measures:

Disable Executors: Set your forge configuration for executors to None.
Secure Executors: Use more secure executors, such as bwrap or container.
Plugin Trust: Only install and enable plugins from trusted sources.
Access Control: Strictly monitor and review all changes to .gitroot/plugins.yml, specifically focusing on authorized system commands.

5. Patch Schedule

6. Security Contact

Transparency and security are core values at GitRoot. If you discover any other potential vulnerabilities or have questions regarding this report, please contact us directly at contact@gitroot.dev.

Modifying the API in the SDK Plugin

rmaneschi@gmail.com (Romain Maneschi) — 2026/04/06

Modifying the API in the SDK Plugin

The last feature for version 0.4 is about adding mv (move) and cp (copy) functions to the SDK plugin. I’m taking advantage of this development to explain how the plumbing works under the hood.

Right now, the SDK plugin is undocumented because there are a lot of breaking changes coming. Every time I develop a new plugin, I discover better ways to do things, and the SDK needs to adapt.

Anyway, I think explaining how the SDK works through a concrete example will be helpful, if not for you, at least for me.

What is the SDK’s job?

Wait, only integers?

When you build a plugin, you just implement an interface. The SDK handles the rest: you receive objects and strings, and you send back data without ever worrying about the underlying WASM pointers.

What does a concrete implementation look like?

When I add a new function, I always start with the host side. All functions are located in runtime.go.

1r.wazRun.
2    NewFunctionBuilder().WithFunc(r.MoveFileBuilder(false)).Export("moveFile").
3    NewFunctionBuilder().WithFunc(r.MoveFileBuilder(true)).Export("moveFileAS")

Then I implement the builder:

 1func (r *runtime) MoveFileBuilder(forAS bool) interface{} {
 2	if !forAS {
 3		return func(_ context.Context, m api.Module, ptr, size, ptr2, size2 uint32) {
 4			// from ptr/size to string or object
 5			r.moveFile(fromPath, toPath)
 6		}
 7	} else {
 8		return func(_ context.Context, m api.Module, ptr, ptr2 uint32) {
 9			// from ptr to string or object
10			r.moveFile(fromPath, toPath)
11		}
12	}
13}

Yeah, I know. As a Gopher, seeing interface{} as a return type and all these uint32 feels wrong. But hey, we’re not here for a code review, we’re here to add an API. If you have a cleaner way, feel free to submit a graft!

We want to allow any plugin to move a file. Let’s define the internal moveFile function:

1func (r *runtime) moveFile(fromPath, toPath string) error {
2	//need to do something...
3}

1func (r *runtime) moveFile(fromFs, fromPath, toFs, toPath string) error {
2	//need to do something...
3}

Now your plugin can call moveFile("cache", "artifacts/myBin", "web", "releases/myBin-v1.0") to publish an artifact, or moveFile("web", "index.html", "web", "old/index.html") to back up a file.

I won’t bore you with the implementation logic here. If you’re curious, check the code.

Here is how the final builder looks, converting pointers to strings:

 1func (r *runtime) MoveFileBuilder(forAS bool) interface{} {
 2	if !forAS {
 3		return func(_ context.Context, m api.Module, fromFsPtr, fromFsSize, fromPathPtr, fromGlobPathSize, toFsPtr, toFsSize, toPathPtr, toPathSize uint32) uint64 {
 4			fromFs, err := r.readString(m, "MoveFile fromFs", fromFsPtr, fromFsSize)
 5			if err != nil {
 6				return r.sendEmptyOrError(m, err)
 7			}
 8			fromPath, err := r.readString(m, "MoveFile fromGlobPath", fromPathPtr, fromGlobPathSize)
 9			if err != nil {
10				return r.sendEmptyOrError(m, err)
11			}
12			toFs, err := r.readString(m, "MoveFile toFs", toFsPtr, toFsSize)
13			if err != nil {
14				return r.sendEmptyOrError(m, err)
15			}
16			toPath, err := r.readString(m, "MoveFile toPath", toPathPtr, toPathSize)
17			if err != nil {
18				return r.sendEmptyOrError(m, err)
19			}
20			return r.sendEmptyOrError(m, r.moveFile(fromFs, fromPath, toFs, toPath))
21		}
22	} else {
23		return func(_ context.Context, m api.Module, fromFsPtr, fromPathPtr, toFsPtr, toPathPtr uint32) uint64 {
24			fromFs, err := r.readASString(m, "MoveFileAS fromFs", fromFsPtr)
25			if err != nil {
26				return r.sendEmptyOrError(m, err)
27			}
28			fromPath, err := r.readASString(m, "MoveFileAS fromGlobPath", fromPathPtr)
29			if err != nil {
30				return r.sendEmptyOrError(m, err)
31			}
32			toFs, err := r.readASString(m, "MoveFileAS toFs", toFsPtr)
33			if err != nil {
34				return r.sendEmptyOrError(m, err)
35			}
36			toPath, err := r.readASString(m, "MoveFileAS toPath", toPathPtr)
37			if err != nil {
38				return r.sendEmptyOrError(m, err)
39			}
40			return r.sendEmptyOrError(m, r.moveFile(fromFs, fromPath, toFs, toPath))
41		}
42	}
43}

Inside the SDK

In the server interface:

1type Server interface {
2    //...
3    MoveFile(fromFs, fromPath, toFs, toPath string) error
4    //...
5}

To make it more “user-friendly”, I use a struct to represent the filesystem in model/fs.go:

1func (g *GrFs) MoveFile(fromPath string, toPath string) error {
2    return g.server.MoveFile(g.base, fromPath, g.base, toPath)
3}
4
5func (g *GrFs) MoveFileToFs(fromPath string, toFs *GrFs, toPath string) error {
6    return g.server.MoveFile(g.base, fromPath, toFs.base, toPath)
7}

The actual WASM call happens in plugin/server.go, where we transform strings back into pointers:

 1// MoveFile implements [model.ServerNeeded].
 2func (s *pServer) MoveFile(fromFs model.FsBase, fromPath string, toFs model.FsBase, toPath string) error {
 3	ptr, size := stringToPtr(string(fromFs))
 4	ptr2, size2 := stringToPtr(fromPath)
 5	ptr3, size3 := stringToPtr(string(toFs))
 6	ptr4, size4 := stringToPtr(toPath)
 7	resPtrSize := _moveFile(ptr, size, ptr2, size2, ptr3, size3, ptr4, size4)
 8	runtime.KeepAlive(fromFs)
 9	runtime.KeepAlive(fromPath)
10	runtime.KeepAlive(toFs)
11	runtime.KeepAlive(toPath)
12	return ptrSizeToError(resPtrSize)
13}

And finally, the link to the host via go:wasmimport in plugin/imports.go:

1//go:wasmimport gitroot moveFile
2func _moveFile(fromFsPtr, fromFsSize, fromPathPtr, fromPathSize, toFsPtr, toFsSize, toPathPtr, toPathSize uint32) (ptrSize uint64)

How to use it?

Now, any plugin can use this. Here’s a simple Go plugin that triggers a build whenever a .go file is modified and moves the binary to the web folder.

 1package main
 2
 3import (
 4	"fmt"
 5	"path/filepath"
 6	"strings"
 7
 8	gitroot "gitroot.dev/libs/golang/plugin"
 9	"gitroot.dev/libs/golang/plugin/model"
10)
11
12var defaultRun = []model.PluginRun{{
13	Path:   "**/*.go",
14	When:   model.PluginRunWhenAll,
15	Branch: []string{"main"},
16	Write: model.PluginWrite{
17		Web: []model.PluginWriteRight{{
18			Path: "releases/main",
19			Can:  model.PluginWriteRightCanAll,
20		}},
21	},
22}}
23
24type Plugin struct {
25	server model.Server
26    needToBuild bool
27}
28
29func (p *Plugin) Init(repoName string, confHasChanged bool, serializedConf string) error {
30    p.needToBuild = false
31    return nil
32}
33
34func (p *Plugin) StartCommit(commit model.Commit) error                                  { return nil }
35
36func (p *Plugin) AddFile(file model.File) error                                          {
37	p.needToBuild = true
38    return nil
39}
40
41func (p *Plugin) ModFile(file model.File) error                                          {
42	p.needToBuild = true
43    return nil
44}
45
46func (p *Plugin) DelFile(file model.File) error                                          {
47	p.needToBuild = true
48    return nil
49}
50
51func (p *Plugin) EndCommit(commit model.Commit) error                                    { return nil }
52
53func (p *Plugin) Finish() error                                                          {
54    if p.needToBuild {
55        res, _ := p.server.Exec(model.Exec{
56            Cmds: []model.Cmd{
57                {Cmd: "go", Args: []string{"build"}},
58            },
59            Artifacts: []string{"main"},
60        })
61        return p.server.Cache().MoveFileToFs(res.Artifacts[0], p.server.Webcontent(), filepath.Join("releases", "main"))
62	}
63    return nil
64}
65
66func Build(server model.Server) model.Plugin {
67	return &Plugin{
68		server: server,
69	}
70}
71
72//go:wasmexport install
73func main() {
74	gitroot.Register(defaultRun, Build)
75}

Is that all?

Nope. I still need to update the Rust and AssemblyScript SDKs and, of course, add tests. But this should give you a good idea of how the plumbing works.

If anything is unclear, let me know!

Comment contribuer au développement de GitRoot

rmaneschi@gmail.com (Romain Maneschi) — 2025/11/18

Comment contribuer au développement de GitRoot 11-2025

Alors pourquoi pas de contributeurs externes sur GitRoot ?

Pré-requis

Il n’y a pas grand chose à faire pour être prêt à aider sur GitRoot:

vous devez avoir git
git clone ssh://gitroot.dev
cd gitroot.dev
./gitroot/init.sh

Si vous souhaitez coder il vous faudra en plus:

bash et make (si vous êtes dev il y a de grandes chances que vous les aillez déjà)
installer mise, c’est le plus simple pour avoir tous les compilateurs dans les bonnes versions

Avant de commencer

On peut également en parler par mail contact@gitroot.dev ou sur le fediverse ^{[forge@gitrrot.dev]}(https://gts.gitroot.dev/@forge).

Qu’est-ce qu’on peut faire ?

Corriger les fautes

Moi je veux faire du web

Quand vous êtes content faites une branche avec votre css dans apex, puis git add . et git push je m’occupe du reste.

Moi je veux coder

Bien, pas de soucis, voici une liste de petites tâches (enfin elles me paraissent petites mais si c’est pas le cas pour vous dites le moi):

en golang:
- dans le plugin grafter pouvoir afficher autre chose dans le 1er message d’un graft. La bannière est en dure dans le plugin, il faudrait l’exporter dans la conf du plugin et l’utiliser.
- dans le plugin silo permettre de grouper par fichier ou date
- plus difficile mais j’aimerais bien avoir plus de renderer dans apex, par exemple les infos, warning et autre
en typescript:
- dans le plugin pollen il y a un bug sur le rss il est jamais nettoyé. Rajouté une option (ou pas, 100 en dur me semble être déjà pas mal) pour limiter le nombre d’<item>.
- toujours dans le plugin pollen pourquoi pas rajouter un json feed en plus du rss. On peut serializer du json en assemblescript.
- plus difficile mais il serait bien de pouvoir dire au plugin pollen de générer un rss avec le contenu des fichiers. Ça permettrait à GitRoot d’avoir un rss affichant les articles du blog par exemple. Aujourd’hui il ne met dans le rss que les commits.
en rust:
- faire ce que Ygor à dit dans https://floss.social/@ygor/115474535138702961 je ne suis pas un developpeur rust et transformer des String en &str me parle pas beaucoup mais si vous l’êtes je suis sûr que c’est une petite tâche. Le code se trouve dans le plugin sdk et le plugin hop.
- ajouter un fakeServer au plugin sdk pour faciliter les tests d’un plugin, voici celui de go https://gitroot.dev/worktree/app/libs/golang/plugin/test/fakeserver.go.html

Moi je suis sysadmin

Parfait il y a de quoi faire aussi:

aujourd’hui il y a trop d’étapes pour releaser GitRoot, automatiser au maximum m’aiderais beaucoup.
si vous avez un petit de place sur un de vos serveurs, tester de déployer une instance juste pour le fun. Peu être vous pourrez améliorer la doc ou trouver quelque chose qui ne marche plus. Ou ajouter un paragraphe pour utiliser gitroot avec nginx ou autre.

Moi je veux tester

tous les tests sont en bash dans testsuite/runtest.sh se trouve le plus gros test, à côté il y en d’autres
- exécutez les pour voir s’ils marchent chez vous me parait une bonne première tâche
- en créer de nouveaux
- améliorer les existants en sortant par exemple des fonctions helper comme quiet_git(), report() ou mySleep() dans d’autres fichiers (et les importer) serait d’une grande aide pour le projet. Vous pouvez aussi créer des nouveaux pour killGitroot() qui est fait en début de chaque fichier. Ou createProject() qui consiste à chaque fois à aller dans le root repository et ajouter son nom dans le fichier .gitroot/repositories.yml.

Moi je veux juste réfléchir/discutter

Tu es le bienvenue sur le channel gitroot dans matrix. Ou par mail contact [AT] gitroot.dev ou sur le fediverse @forge@gitroot.dev sur ce serveur.

How to help building GitRoot

rmaneschi@gmail.com (Romain Maneschi) — 2025/11/18

How to help building GitRoot 11-2025

This article is the translation of french version thanks to DeepL

So why not have external contributors on GitRoot?

Prerequisites

There isn’t much you need to do to get ready to help out on GitRoot:

you need to have git
git clone ssh://gitroot.dev
cd gitroot.dev
./gitroot/init.sh

If you want to code, you will also need:

bash and make (if you are a developer, chances are you already have them)
Install mise, which is the easiest way to get all the right versions of the compilers

Before we begin

We can also talk about it by email contact@gitroot.dev or on the fediverse ^{[forge@gitrrot.dev]}(https://gts.gitroot.dev/@forge).

What can we do?

Correct mistakes

I want to work on the web

It would be great to create (or find) a theme. GitRoot currently uses simplecss, and it only needs classless CSS. There are many available, but you can also create one for GitRoot.

When you are satisfied, create a branch with your CSS in apex, then git add . and git push. I’ll take care of the rest.

I want to code

Okay, no worries, here’s a list of small tasks (well, they seem small to me, but if that’s not the case for you, let me know):

in golang:
- in the grafter plugin, be able to display something else in the first message of a graft. The banner is hard-coded in the plugin; it would need to be exported to the plugin configuration and used.
- In the silo plugin, allow grouping by file or date
- More difficult, but I would like to have more renderers in apex, for example info, warnings, and others
in typescript:
- in the pollen plugin there is a bug in the RSS feed it is never cleaned up. Added an option (or not, 100 seems fine to me) to limit the number of <item>.
- Still in the pollen plugin, why not add a json feed in addition to the RSS feed? We can serialize json in assemblescript.
- More difficult, but it would be nice to be able to tell the pollen plugin to generate an RSS feed with the contents of the files. This would allow GitRoot to have an RSS feed displaying blog articles, for example. Currently, it only puts commits in the RSS feed.
in Rust:
- Do what Ygor said in https://floss.social/@ygor/115474535138702961 I’m not a Rust developer and converting String to &str doesn’t mean much to me, but if you are, I’m sure it’s a small task. The code can be found in the plugin sdk and the hop plugin.
- Add a fakeServer to the plugin sdk to facilitate plugin testing. Here is the one for Go https://gitroot.dev/worktree/app/libs/golang/plugin/test/fakeserver.go.html

I’m a sysadmin.

Perfect, there’s plenty to do:

Today, there are too many steps to release GitRoot. Automating as much as possible would help me a lot.
If you have a little space on one of your servers, try deploying an instance just for fun. Maybe you can improve the documentation or find something that no longer works. Or add a paragraph on using gitroot with nginx or something else.

I want to test

All tests are in bash in /app/testsuite/. The largest test is located in runtest.sh, along with others.
- Running them to see if they work on your system seems like a good first task to me.
- Creating new ones
- Improving existing ones by, for example, moving helper functions such as quiet_git(), report(), or mySleep() to other files (and importing them) would be a great help to the project. You can also create new ones for killGitroot(), which is done at the beginning of each file. Or createProject(), which consists of going to the root repository each time and adding its name to the .gitroot/repositories.yml file

I just want to think/discuss

You are welcome to join the gitroot channel on Matrix. Or contact us by email at contact [AT] gitroot.dev or on the Fediverse at @forge@gitroot.dev on this server.

Issues, Tickets, Discussions... Call them what you want!

rmaneschi@gmail.com (Romain Maneschi) — 2026/06/08

Issues, Tickets, Discussions… Call them what you want!

Many of you, when checking out https://gitroot.dev, have told me that the 🐞 Issues button shouldn’t be labeled “Issues”, but rather “Tickets” or “Discussions”.

The Original Idea

In traditional forges, an “issue” consists of a title and a description created by a user. We can represent it like this:

Easy, right? Well, how do you represent that in GitRoot using only files? This question was running through my mind for months before I finally found a solution.

The Basic Solution

A simple text format that handles metadata perfectly is Markdown. I use Markdown here, but any other markup language could work. Let’s create a file named issues/1.md:

1---
2id: 1
3user: email@email.com
4status: OPEN
5---
6
7# My title
8
9My description where I can detail what my problem is.

Yes, it really is that simple. In GitRoot, to create an issue, you just create a file, add some metadata, commit, and push. Boom, you have an issue.

A Better Solution

1# My title
2
3My description where I can detail what my problem is.

Then, we run git commit && git push. Since I have configured the ladybug plugin like this:

 1- name: ladybug
 2  ...
 3  - path: issues/**/*.md
 4    branch:
 5    - "*"
 6    when:
 7    - add
 8    - mod
 9    func: []
10    write:
11      git:
12      - path: issues/**/*.md
13        can:
14        - mod
15      web: []
16      exec: []
17      callfunc: []
18    configuration:
19      metadata:
20      - default: autogenerated
21        mandatory: true
22        name: id
23        type: crc16
24      - default: OPEN
25        mandatory: true
26        name: status
27        type: string
28      - default: email@email.com
29        mandatory: false
30        name: user
31        type: string

You can read this configuration as: “For every Markdown file in the issues directory across all branches, if the file doesn’t have these metadata fields, automatically add these default values.”

Now, if you are a Git purist, a server creating commits right on top of yours might sound a bit radical, or even terrifying. But look closely at the write block in the YAML configuration above:

1write:
2  git:
3    - path: issues/**/*.md
4      can:
5        - mod

So, once you push, the server-side plugin does its job, and the next time you run git pull, your local file will automatically look like this:

1---
2id: 1
3user: email@email.com
4status: OPEN
5---
6
7# My title
8
9My description where I can detail what my problem is.

So, What About the Label?

First, we need a file that lists all of these “issues”. That’s exactly why the silo plugin exists. It inspects all files and groups them whenever it finds a matching pattern.

To list all open “issues”, we configure it like this:

 1- name: silo
 2  ...
 3  run:
 4  - path: "**/*"
 5    branch:
 6    - main
 7    when:
 8    - add
 9    - mod
10    - del
11    func: []
12    write:
13      git:
14      - path: boards/*.md
15        can:
16        - add
17        - mod
18        - del
19        - append
20      web: []
21      exec: []
22      callfunc: []
23    configuration:
24      boards:
25        description: All open issues
26        for: issues/*.md
27        format: table
28        paginator: 50
29        selects:
30        - "status: (.*)"
31        - "user: (.*)"
32        sort: select[0]
33        sortOrder: desc
34        tableHeader: "| | status | user |"
35        title: All issues
36        to: boards/issues.md
37        where: "status: OPEN"

You can read this configuration as: “For every file in the main branch, create a board called ‘All issues’ containing links to all files matching status: OPEN. Display them as a table with status and user columns.”

After running git commit && git push && git pull, you will get a new file at boards/issues.md containing something like this:

1# All issues
2
3All open issues
4
5|                                   | status | user            |
6| --------------------------------- | ------ | --------------- |
7| [My title](../issues/my_issue.md) | OPEN   | email@email.com |

Now that we have a page representing all our issues, we can finally render it in the browser. Because, as you might have guessed, the label causing all this debate lives in the Web UI.

The Web is Where It Happens

To render my boards/issues.md file on the web, I use the apex plugin, in conjunction with the apex_markdown plugin, of course.

These plugins take files from git and render them directly in the Web UI. I configure them like this:

 1- name: apex
 2  ...
 3  run:
 4  - path: "**/*"
 5    branch:
 6    - main
 7    when:
 8    - add
 9    - mod
10    - del
11    func: []
12    write:
13      git:
14      - path: "**/*"
15        can:
16        - add
17        - mod
18        - del
19        - append
20      web:
21      - path: "**/*"
22        can:
23        - add
24        - mod
25        - del
26        - append
27      exec: []
28      callfunc:
29      - pluginname: apex_markdown
30        funcname: renderMd
31      ...
32    configuration:
33      ...
34      menu:
35      - display: 🏠 Home
36        link: /
37      - display: 📖 Documentation
38        link: /doc/
39      - display: 🔖 Versions
40        link: /CHANGELOG.html
41      - display: �� Plugins
42        link: /plugins/
43      - display: �� Issues
44        link: /boards/issues.html
45      - display: 🚀 Code
46        link: /worktree/
47      - display: ☕ Blog
48        link: /blog/
49      - display: �� Contact
50        link: /contact.html

If you are wondering how Apex magically knows where to find your “issues”, the secret is: it doesn’t.

Conclusion

I’m pretty sure you now understand why I didn’t immediately jump on resolving this task: everything we just saw is pure configuration, completely separated from the GitRoot core code.

In fact, I personally call them TODOs, because in reality, they are all just waiting for me to get them done.

Wait… Why stop at issues?

This is where the true power of GitRoot will blow your mind.

Yes, you read that right. You can visit it live at https://gitroot.dev/boards/todos.html.

If you want to discover more plugins and configurations, feel free to browse through the 🧩 Plugins section. However, for now, the best way to explore remains checking out the actual GitRoot plugins.yml configuration file.

0.5.0

rmaneschi@gmail.com (Romain Maneschi) — 2026/10/05

Move slowly, and take care of things

Thanks to lonugem for the title idea

If you only have 5 minutes

Breaking PURL

Joking aside, you need to replace your plugin URL with a PURL one. ECMA PURL is a specification to produce “a standardized URL-based syntax that uniquely identifies software packages”.

This corresponds to the following change:

1- url: https://gitroot.dev/releases/0.4.0/ladybug-0.0.4.wasm
2- checksum: sha256:7409837469ce89d5c9fd8dd48236764650f48523ff4d81295967154977a01635
3- name: ladybug
4- version: 0.0.4
5+ purl: pkg:gitroot/gitroot/ladybug@0.0.5?checksum=sha256:afb22a26e7d489d72db0a2305d433a3c3ac2692959ba2412011c0d759b4c8518&registry=https:%2F%2Fgitroot.dev%2Freleases%2F0.5.0
6  active: true

Look in the plugins registry to find the exact purl for each plugin.

To know why, how and more read purl details.

A lot of people have discovered GitRoot

First show, first lobste.rs/HN links, first video… Yes, more and more people are talking about GitRoot. Discover where.

Not conclusive

Before it’s too late

My new favorite language…. until the next one

Plugins needs more power

Sftp to save the web

How many bugs?

A lot of bug fixes have been done. Let me explain some interesting ones.

In-depth Details

PURL breaking details

Another example is if someone forks ladybug and wants to release it in the registry. Previously there was no option to do that, so adding a scope seemed to be the best choice.

That was a big refactor to do, but I’m pretty happy with the result.

GitRoot communication

A lot has occured during this summer, on the communication side too.

And GitRoot has been added to AlternativeTo. I don’t know if this will lead to anything, but hey, I’m right alongside GitHub and GitLab :P

SdkGenerator full story

Max anonymous branches

Zig plugin-sdk

PluginSdk improvements

Regarding the plugin-sdk, here are a lot of new capabilities for plugins to use:

schedule: you can allow a plugin to be called at a scheduled time. The format is a cron expression with 5 segments as <minute> <hour> <day> <month> <weekday>. Example:

1- purl: pkg:gitroot/gitroot/firefly@0.0.1?checksum=sha256:fae956f5cc9239a87b1c2a149a5466fec85476377de4ada33dda190edb3700c4&registry=https:%2F%2Fgitroot.dev%2Freleases%2F0.5.0
2  active: true
3  run:
4    - path: ""
5      branch:
6        - main
7      when: []
8      schedule: "* * * * *"

That means the firefly plugin will be executed on the main branch every minute. Refer to the gronx library documentation for cron expression details.

1callFunc:
2  - pluginPURL: pkg:gitroot/gitroot/apex
3    funcName: renderHtml
4    configuration:
5      branchesDir: branches
6      favicon: logo.png
7      footer: <p>Start with <code>git clone ssh://gitroot.dev/</code> 🚀</p><small>Hosted with ❤️ by Gitroot</small>
8      generateGitWorktree: true
9      header: ...

Sftp feature

Be careful: this feature is in alpha, so don’t write scripts around it for now. I will probably change the directory hierarchy #d42a.

Some interesting bug fixes

What next?

Then I will probably start working on:

Discover GitRoot without installing anything.
Create your own plugins with ease.
Transform GitRoot into a registry for (at least) Go, Rust, NPM and Zig.
Federation with GitRoot but also other forges.
Implement something for users (how to represent them).
Manage more Git functions in plugins (branch, pull, push, rebase).
Use pull-iterators to stabilise the plugin-sdk.
Easier configuration of plugins.
Auto-update of plugins.
New language plugin-sdk.
Air-gapped version of GitRoot.
Make every repository a gemini capsule.

Special thanks to Ryuno-Ki, Matthieu and ks from the #gitroot:matrix.org Matrix room for reviewing and correcting this article. Want to help with future posts? Join us in the room!

0.4.0

rmaneschi@gmail.com (Romain Maneschi) — 2026/04/22

The teenager starts building its own future

If you only have 5 minutes

If you skim this article, don’t forget to check out the conclusion about “what’s next?”.

The thing i’m most proud of

Executors can finally build GitRoot! As I love to say: GitRoot can build GitRoot on GitRoot. And it was a pain to do. Read more.

The thing with the most visibility

The thing that changes everything but was so simple

The thing that was more complex than I thought

The things I’m just happy are done

No more mandatory signed commits! Well, it’s still better if you sign them, but this change means the .gitroot/init.sh has been ~~deleted~~ moved to a plugin. Read more.

In-depth Details

Executor

Still not the end! After that, I needed to configure port numbers, so I built a complete environment variable system, and used it to configure some mise paths.

But hey, let’s celebrate what we’ve built before jumping into the next sprint!

Plugin registry

Apex render branch

Elegant, but honestly, a total over-engineered mess. When I actually sat down to code this, I ended up adding just two lines to the apex plugin:

1if p.currentCommit.Branch != "" && p.currentCommit.Branch != p.config.defaultBranch {
2	path = filepath.Join(p.config.branchesDir, p.currentCommit.Branch, path)
3}

Plugin deps

So, I started building the apex_markdown plugin, then apex_code, and next week apex_mermaid. But what I hadn’t fully anticipated was the sheer amount of work required to make it all work together.

With this in place, I’m not even sure if I’ll keep the report system, which was an other way of passing information between plugins.

Sigma plugin

Now, you have the choice to accept unsigned commits in your repo. You can even ignore the whole signing topic entirely if you don’t install the stigma plugin.

That said, I’m still convinced that signing commits should remain the default.

FS plugin-sdk

I have marked all old methods as deprecated, and they will be removed in the next version of GitRoot (or more specifically, the plugin-sdk, though they share the same release number for now).

What next?

I have a massive roadmap for GitRoot (in no particular order):

Discover GitRoot without installing anything.
Create your own plugins with ease.
Transform GitRoot into a registry for (at least) Go, Rust, and NPM.
Plugins should be usable via PURL.
Plugins can send/receive HTTP requests.
Plugins can be scheduled.
Rebase go-git to take advantage of their performance improvements.
Generate the plugin SDK automatically.
Add plugin SDKs for (at least) Zig, Kotlin, and Python.

This is only the beginning. GitRoot will get better and better with every release.

0.3.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/12/20

From “baby to teenager” GitRoot become a forge

If you only have 5 minutes

To activate this new capability on your instance, follow the administrator section. To start using it as a user, see the user section.

Finally, I discuss Apex and many other tiny but useful things.

In-depth Details

For admin: activating an executor

When you update GitRoot to 0.3.0 a new configuration block will appear in the .gitroot/forgeConfig.yml file of your root repository:

 1execconf:
 2  baremetal:
 3    enabled: false
 4  bwrap:
 5    enabled: false
 6    user: nobody
 7    uid: 65534
 8    gid: 65534
 9    robind: []
10    bind: []
11  container:
12    enabled: false
13    bin: podman
14  ssh:
15    enabled: false
16    hosts:
17      - user: myUSer
18        address: 127.0.0.1
19        port: 22
20        publickey: ssh-ed25519 AAAAC3NzaC1...

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.

Bare Metal: simplest but most dangerous

Bubblewrap (bwrap): lightweight sandboxing

Container: heavyweight but most flexible

GitRoot 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.

SSH: remote execution (alpha)

For user: using the `hop` plugin

To execute a build (or command execution), users must activate the hop plugin and configure its execution rules:

 1- url: /home/rmaneschi/projects/gitroot/app/testsuite/../plugins/hop/hop-0.0.1.wasm
 2  name: hop
 3  version: 0.0.1
 4  active: true
 5  run:
 6    - path: "*"
 7      branch:
 8        - "*"
 9      when:
10        - add
11        - mod
12      write:
13        git: []
14        web: []
15        exec:
16          - command: cat
17      configuration:
18        exec:
19          build: ""
20          cmds:
21            - args:
22                - README.md
23              cmd: cat
24          env: []

Add all desired commands for the plugin to call in run.write.exec.

Then in run.configuration.exec:

set environment variables via env (e.g., "MY_ENV=my_val")
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)
define the commands and arguments to execute under cmds

Plugin api report and reporter

To allow reporting without forcing a communication channel, I’ve created two new plugin APIs.

Report: 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.

Reporter API: after reports are collected, GitRoot calls all plugins that implement the Reporter interface.

GitRoot bets on mise

Communication and community building

Alongside the technical work for v0.3.0, a focused effort was put into non-technical tasks to improve communication with the community.

I also established a direct chat room on matrix, accessible via https://matrix.to/#/#gitroot:matrix.org. Feel free to stop by to ask questions or just say hello.

Apex a better web experience

The Apex plugin receives numerous bug fixes and quality of life improvements:

favicon support: a favicon can now be added via the configuration
styled 404 page: the 404 error page now correctly uses the site’s CSS
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
menu highlighting: the current page in the navigation menu is now highlighted
lightweight template: added some variables in header and footer templates

And others useful updates

Although this article is already quite long, I want to briefly mention several smaller yet important tasks completed in this release.

ForgeConf update

Integrated updater

Rust and WASM

0.2.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/09/18

Version 0.2.0 is here

First contribution

Although all my new contributions were related to “bug fixes”, some of them required new features.

No notification == no contribution

To follow all gitroot commits follow https://gitroot.dev/rss/all-commits.xml

Lot of bugs

Let’s the show continue

No linux == no gitroot

Doc, doc… doc?

A lot more

As you can see, there were many mistakes in the first version. However, they have all been fixed, and, of course, I have added plenty more to keep me busy for the next version!

More technicals bugs

Simplify plugin install

What next?

With the exception of any new bugs detected for the next iteration, I would like to focus on the following:

creating a plugins marketplace
adding a new language SDK for plugins (Maybe Rust? Or Zig?)
rebasing the Git lib fork and applying patches

0.1.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/09/18

GitRoot 0.1.0 is deployed 🎉��

GitRoot in numbers:

58 commits
+500 files https://gitroot.dev/worktree/
1 issue in gitlab (closed) https://gitlab.com/gitroot/gitroot/-/issues/1
29 issues close https://gitroot.dev/boards/closed.html
43 issues open https://gitroot.dev/boards/issues.html
22 pages de doc https://gitroot.dev/doc/
4 licences https://gitroot.dev/README.html#license
4 plugins https://gitroot.dev/CHANGELOG.html#plugins

But if you retain only one, it is:

1 contributor https://gitroot.dev/worktree/.gitroot/users.yml.html (others are forge and plugins 😭)

So there is only one thig to do… read the doc and contribute!

blog/security-vulnerability-1.md

rmaneschi@gmail.com (Romain Maneschi) — 2026/03/30

Security Advisory: Executor Command Injection

1. Executive Summary

Severity: Moderate
Affected Version: 0.3.0
Fix Status: Scheduled for version 0.4.0

2. Technical Details

3. Impact Analysis

The level of risk depends on your infrastructure configuration:

High Risk: Users utilizing bareMetal or ssh executors.
Low Risk: Users utilizing bubblewrap or container isolation (as the sandbox significantly limits the potential impact on the host).

Exploitability Constraints: This vulnerability is not a “remote code execution” flaw in the traditional sense. Exploitation requires:

Installing a malicious plugin.
Having write access to the default branch of the root repository.
Merging a malicious .gitroot/plugins.yml into the default branch.

4. Immediate Mitigations

If you cannot wait for the 0.4.0 release, we recommend applying the following measures:

Disable Executors: Set your forge configuration for executors to None.
Secure Executors: Use more secure executors, such as bwrap or container.
Plugin Trust: Only install and enable plugins from trusted sources.
Access Control: Strictly monitor and review all changes to .gitroot/plugins.yml, specifically focusing on authorized system commands.

5. Patch Schedule

6. Security Contact

Transparency and security are core values at GitRoot. If you discover any other potential vulnerabilities or have questions regarding this report, please contact us directly at contact@gitroot.dev.

Modifying the API in the SDK Plugin

rmaneschi@gmail.com (Romain Maneschi) — 2026/04/06

Modifying the API in the SDK Plugin

The last feature for version 0.4 is about adding mv (move) and cp (copy) functions to the SDK plugin. I’m taking advantage of this development to explain how the plumbing works under the hood.

Right now, the SDK plugin is undocumented because there are a lot of breaking changes coming. Every time I develop a new plugin, I discover better ways to do things, and the SDK needs to adapt.

Anyway, I think explaining how the SDK works through a concrete example will be helpful, if not for you, at least for me.

What is the SDK’s job?

Wait, only integers?

When you build a plugin, you just implement an interface. The SDK handles the rest: you receive objects and strings, and you send back data without ever worrying about the underlying WASM pointers.

What does a concrete implementation look like?

When I add a new function, I always start with the host side. All functions are located in runtime.go.

1r.wazRun.
2    NewFunctionBuilder().WithFunc(r.MoveFileBuilder(false)).Export("moveFile").
3    NewFunctionBuilder().WithFunc(r.MoveFileBuilder(true)).Export("moveFileAS")

Then I implement the builder:

 1func (r *runtime) MoveFileBuilder(forAS bool) interface{} {
 2	if !forAS {
 3		return func(_ context.Context, m api.Module, ptr, size, ptr2, size2 uint32) {
 4			// from ptr/size to string or object
 5			r.moveFile(fromPath, toPath)
 6		}
 7	} else {
 8		return func(_ context.Context, m api.Module, ptr, ptr2 uint32) {
 9			// from ptr to string or object
10			r.moveFile(fromPath, toPath)
11		}
12	}
13}

Yeah, I know. As a Gopher, seeing interface{} as a return type and all these uint32 feels wrong. But hey, we’re not here for a code review, we’re here to add an API. If you have a cleaner way, feel free to submit a graft!

We want to allow any plugin to move a file. Let’s define the internal moveFile function:

1func (r *runtime) moveFile(fromPath, toPath string) error {
2	//need to do something...
3}

1func (r *runtime) moveFile(fromFs, fromPath, toFs, toPath string) error {
2	//need to do something...
3}

Now your plugin can call moveFile("cache", "artifacts/myBin", "web", "releases/myBin-v1.0") to publish an artifact, or moveFile("web", "index.html", "web", "old/index.html") to back up a file.

I won’t bore you with the implementation logic here. If you’re curious, check the code.

Here is how the final builder looks, converting pointers to strings:

 1func (r *runtime) MoveFileBuilder(forAS bool) interface{} {
 2	if !forAS {
 3		return func(_ context.Context, m api.Module, fromFsPtr, fromFsSize, fromPathPtr, fromGlobPathSize, toFsPtr, toFsSize, toPathPtr, toPathSize uint32) uint64 {
 4			fromFs, err := r.readString(m, "MoveFile fromFs", fromFsPtr, fromFsSize)
 5			if err != nil {
 6				return r.sendEmptyOrError(m, err)
 7			}
 8			fromPath, err := r.readString(m, "MoveFile fromGlobPath", fromPathPtr, fromGlobPathSize)
 9			if err != nil {
10				return r.sendEmptyOrError(m, err)
11			}
12			toFs, err := r.readString(m, "MoveFile toFs", toFsPtr, toFsSize)
13			if err != nil {
14				return r.sendEmptyOrError(m, err)
15			}
16			toPath, err := r.readString(m, "MoveFile toPath", toPathPtr, toPathSize)
17			if err != nil {
18				return r.sendEmptyOrError(m, err)
19			}
20			return r.sendEmptyOrError(m, r.moveFile(fromFs, fromPath, toFs, toPath))
21		}
22	} else {
23		return func(_ context.Context, m api.Module, fromFsPtr, fromPathPtr, toFsPtr, toPathPtr uint32) uint64 {
24			fromFs, err := r.readASString(m, "MoveFileAS fromFs", fromFsPtr)
25			if err != nil {
26				return r.sendEmptyOrError(m, err)
27			}
28			fromPath, err := r.readASString(m, "MoveFileAS fromGlobPath", fromPathPtr)
29			if err != nil {
30				return r.sendEmptyOrError(m, err)
31			}
32			toFs, err := r.readASString(m, "MoveFileAS toFs", toFsPtr)
33			if err != nil {
34				return r.sendEmptyOrError(m, err)
35			}
36			toPath, err := r.readASString(m, "MoveFileAS toPath", toPathPtr)
37			if err != nil {
38				return r.sendEmptyOrError(m, err)
39			}
40			return r.sendEmptyOrError(m, r.moveFile(fromFs, fromPath, toFs, toPath))
41		}
42	}
43}

Inside the SDK

In the server interface:

1type Server interface {
2    //...
3    MoveFile(fromFs, fromPath, toFs, toPath string) error
4    //...
5}

To make it more “user-friendly”, I use a struct to represent the filesystem in model/fs.go:

1func (g *GrFs) MoveFile(fromPath string, toPath string) error {
2    return g.server.MoveFile(g.base, fromPath, g.base, toPath)
3}
4
5func (g *GrFs) MoveFileToFs(fromPath string, toFs *GrFs, toPath string) error {
6    return g.server.MoveFile(g.base, fromPath, toFs.base, toPath)
7}

The actual WASM call happens in plugin/server.go, where we transform strings back into pointers:

 1// MoveFile implements [model.ServerNeeded].
 2func (s *pServer) MoveFile(fromFs model.FsBase, fromPath string, toFs model.FsBase, toPath string) error {
 3	ptr, size := stringToPtr(string(fromFs))
 4	ptr2, size2 := stringToPtr(fromPath)
 5	ptr3, size3 := stringToPtr(string(toFs))
 6	ptr4, size4 := stringToPtr(toPath)
 7	resPtrSize := _moveFile(ptr, size, ptr2, size2, ptr3, size3, ptr4, size4)
 8	runtime.KeepAlive(fromFs)
 9	runtime.KeepAlive(fromPath)
10	runtime.KeepAlive(toFs)
11	runtime.KeepAlive(toPath)
12	return ptrSizeToError(resPtrSize)
13}

And finally, the link to the host via go:wasmimport in plugin/imports.go:

1//go:wasmimport gitroot moveFile
2func _moveFile(fromFsPtr, fromFsSize, fromPathPtr, fromPathSize, toFsPtr, toFsSize, toPathPtr, toPathSize uint32) (ptrSize uint64)

How to use it?

Now, any plugin can use this. Here’s a simple Go plugin that triggers a build whenever a .go file is modified and moves the binary to the web folder.

 1package main
 2
 3import (
 4	"fmt"
 5	"path/filepath"
 6	"strings"
 7
 8	gitroot "gitroot.dev/libs/golang/plugin"
 9	"gitroot.dev/libs/golang/plugin/model"
10)
11
12var defaultRun = []model.PluginRun{{
13	Path:   "**/*.go",
14	When:   model.PluginRunWhenAll,
15	Branch: []string{"main"},
16	Write: model.PluginWrite{
17		Web: []model.PluginWriteRight{{
18			Path: "releases/main",
19			Can:  model.PluginWriteRightCanAll,
20		}},
21	},
22}}
23
24type Plugin struct {
25	server model.Server
26    needToBuild bool
27}
28
29func (p *Plugin) Init(repoName string, confHasChanged bool, serializedConf string) error {
30    p.needToBuild = false
31    return nil
32}
33
34func (p *Plugin) StartCommit(commit model.Commit) error                                  { return nil }
35
36func (p *Plugin) AddFile(file model.File) error                                          {
37	p.needToBuild = true
38    return nil
39}
40
41func (p *Plugin) ModFile(file model.File) error                                          {
42	p.needToBuild = true
43    return nil
44}
45
46func (p *Plugin) DelFile(file model.File) error                                          {
47	p.needToBuild = true
48    return nil
49}
50
51func (p *Plugin) EndCommit(commit model.Commit) error                                    { return nil }
52
53func (p *Plugin) Finish() error                                                          {
54    if p.needToBuild {
55        res, _ := p.server.Exec(model.Exec{
56            Cmds: []model.Cmd{
57                {Cmd: "go", Args: []string{"build"}},
58            },
59            Artifacts: []string{"main"},
60        })
61        return p.server.Cache().MoveFileToFs(res.Artifacts[0], p.server.Webcontent(), filepath.Join("releases", "main"))
62	}
63    return nil
64}
65
66func Build(server model.Server) model.Plugin {
67	return &Plugin{
68		server: server,
69	}
70}
71
72//go:wasmexport install
73func main() {
74	gitroot.Register(defaultRun, Build)
75}

Is that all?

Nope. I still need to update the Rust and AssemblyScript SDKs and, of course, add tests. But this should give you a good idea of how the plumbing works.

If anything is unclear, let me know!

Comment contribuer au développement de GitRoot

rmaneschi@gmail.com (Romain Maneschi) — 2025/11/18

Comment contribuer au développement de GitRoot 11-2025

Alors pourquoi pas de contributeurs externes sur GitRoot ?

Pré-requis

Il n’y a pas grand chose à faire pour être prêt à aider sur GitRoot:

vous devez avoir git
git clone ssh://gitroot.dev
cd gitroot.dev
./gitroot/init.sh

Si vous souhaitez coder il vous faudra en plus:

bash et make (si vous êtes dev il y a de grandes chances que vous les aillez déjà)
installer mise, c’est le plus simple pour avoir tous les compilateurs dans les bonnes versions

Avant de commencer

On peut également en parler par mail contact@gitroot.dev ou sur le fediverse ^{[forge@gitrrot.dev]}(https://gts.gitroot.dev/@forge).

Qu’est-ce qu’on peut faire ?

Corriger les fautes

Moi je veux faire du web

Quand vous êtes content faites une branche avec votre css dans apex, puis git add . et git push je m’occupe du reste.

Moi je veux coder

Bien, pas de soucis, voici une liste de petites tâches (enfin elles me paraissent petites mais si c’est pas le cas pour vous dites le moi):

en golang:
- dans le plugin grafter pouvoir afficher autre chose dans le 1er message d’un graft. La bannière est en dure dans le plugin, il faudrait l’exporter dans la conf du plugin et l’utiliser.
- dans le plugin silo permettre de grouper par fichier ou date
- plus difficile mais j’aimerais bien avoir plus de renderer dans apex, par exemple les infos, warning et autre
en typescript:
- dans le plugin pollen il y a un bug sur le rss il est jamais nettoyé. Rajouté une option (ou pas, 100 en dur me semble être déjà pas mal) pour limiter le nombre d’<item>.
- toujours dans le plugin pollen pourquoi pas rajouter un json feed en plus du rss. On peut serializer du json en assemblescript.
- plus difficile mais il serait bien de pouvoir dire au plugin pollen de générer un rss avec le contenu des fichiers. Ça permettrait à GitRoot d’avoir un rss affichant les articles du blog par exemple. Aujourd’hui il ne met dans le rss que les commits.
en rust:
- faire ce que Ygor à dit dans https://floss.social/@ygor/115474535138702961 je ne suis pas un developpeur rust et transformer des String en &str me parle pas beaucoup mais si vous l’êtes je suis sûr que c’est une petite tâche. Le code se trouve dans le plugin sdk et le plugin hop.
- ajouter un fakeServer au plugin sdk pour faciliter les tests d’un plugin, voici celui de go https://gitroot.dev/worktree/app/libs/golang/plugin/test/fakeserver.go.html

Moi je suis sysadmin

Parfait il y a de quoi faire aussi:

aujourd’hui il y a trop d’étapes pour releaser GitRoot, automatiser au maximum m’aiderais beaucoup.
si vous avez un petit de place sur un de vos serveurs, tester de déployer une instance juste pour le fun. Peu être vous pourrez améliorer la doc ou trouver quelque chose qui ne marche plus. Ou ajouter un paragraphe pour utiliser gitroot avec nginx ou autre.

Moi je veux tester

tous les tests sont en bash dans testsuite/runtest.sh se trouve le plus gros test, à côté il y en d’autres
- exécutez les pour voir s’ils marchent chez vous me parait une bonne première tâche
- en créer de nouveaux
- améliorer les existants en sortant par exemple des fonctions helper comme quiet_git(), report() ou mySleep() dans d’autres fichiers (et les importer) serait d’une grande aide pour le projet. Vous pouvez aussi créer des nouveaux pour killGitroot() qui est fait en début de chaque fichier. Ou createProject() qui consiste à chaque fois à aller dans le root repository et ajouter son nom dans le fichier .gitroot/repositories.yml.

Moi je veux juste réfléchir/discutter

Tu es le bienvenue sur le channel gitroot dans matrix. Ou par mail contact [AT] gitroot.dev ou sur le fediverse @forge@gitroot.dev sur ce serveur.

How to help building GitRoot

rmaneschi@gmail.com (Romain Maneschi) — 2025/11/18

How to help building GitRoot 11-2025

This article is the translation of french version thanks to DeepL

So why not have external contributors on GitRoot?

Prerequisites

There isn’t much you need to do to get ready to help out on GitRoot:

you need to have git
git clone ssh://gitroot.dev
cd gitroot.dev
./gitroot/init.sh

If you want to code, you will also need:

bash and make (if you are a developer, chances are you already have them)
Install mise, which is the easiest way to get all the right versions of the compilers

Before we begin

We can also talk about it by email contact@gitroot.dev or on the fediverse ^{[forge@gitrrot.dev]}(https://gts.gitroot.dev/@forge).

What can we do?

Correct mistakes

I want to work on the web

It would be great to create (or find) a theme. GitRoot currently uses simplecss, and it only needs classless CSS. There are many available, but you can also create one for GitRoot.

When you are satisfied, create a branch with your CSS in apex, then git add . and git push. I’ll take care of the rest.

I want to code

Okay, no worries, here’s a list of small tasks (well, they seem small to me, but if that’s not the case for you, let me know):

in golang:
- in the grafter plugin, be able to display something else in the first message of a graft. The banner is hard-coded in the plugin; it would need to be exported to the plugin configuration and used.
- In the silo plugin, allow grouping by file or date
- More difficult, but I would like to have more renderers in apex, for example info, warnings, and others
in typescript:
- in the pollen plugin there is a bug in the RSS feed it is never cleaned up. Added an option (or not, 100 seems fine to me) to limit the number of <item>.
- Still in the pollen plugin, why not add a json feed in addition to the RSS feed? We can serialize json in assemblescript.
- More difficult, but it would be nice to be able to tell the pollen plugin to generate an RSS feed with the contents of the files. This would allow GitRoot to have an RSS feed displaying blog articles, for example. Currently, it only puts commits in the RSS feed.
in Rust:
- Do what Ygor said in https://floss.social/@ygor/115474535138702961 I’m not a Rust developer and converting String to &str doesn’t mean much to me, but if you are, I’m sure it’s a small task. The code can be found in the plugin sdk and the hop plugin.
- Add a fakeServer to the plugin sdk to facilitate plugin testing. Here is the one for Go https://gitroot.dev/worktree/app/libs/golang/plugin/test/fakeserver.go.html

I’m a sysadmin.

Perfect, there’s plenty to do:

Today, there are too many steps to release GitRoot. Automating as much as possible would help me a lot.
If you have a little space on one of your servers, try deploying an instance just for fun. Maybe you can improve the documentation or find something that no longer works. Or add a paragraph on using gitroot with nginx or something else.

I want to test

All tests are in bash in /app/testsuite/. The largest test is located in runtest.sh, along with others.
- Running them to see if they work on your system seems like a good first task to me.
- Creating new ones
- Improving existing ones by, for example, moving helper functions such as quiet_git(), report(), or mySleep() to other files (and importing them) would be a great help to the project. You can also create new ones for killGitroot(), which is done at the beginning of each file. Or createProject(), which consists of going to the root repository each time and adding its name to the .gitroot/repositories.yml file

I just want to think/discuss

You are welcome to join the gitroot channel on Matrix. Or contact us by email at contact [AT] gitroot.dev or on the Fediverse at @forge@gitroot.dev on this server.

Issues, Tickets, Discussions... Call them what you want!

rmaneschi@gmail.com (Romain Maneschi) — 2026/06/08

Issues, Tickets, Discussions… Call them what you want!

Many of you, when checking out https://gitroot.dev, have told me that the 🐞 Issues button shouldn’t be labeled “Issues”, but rather “Tickets” or “Discussions”.

The Original Idea

In traditional forges, an “issue” consists of a title and a description created by a user. We can represent it like this:

Easy, right? Well, how do you represent that in GitRoot using only files? This question was running through my mind for months before I finally found a solution.

The Basic Solution

A simple text format that handles metadata perfectly is Markdown. I use Markdown here, but any other markup language could work. Let’s create a file named issues/1.md:

1---
2id: 1
3user: email@email.com
4status: OPEN
5---
6
7# My title
8
9My description where I can detail what my problem is.

Yes, it really is that simple. In GitRoot, to create an issue, you just create a file, add some metadata, commit, and push. Boom, you have an issue.

A Better Solution

1# My title
2
3My description where I can detail what my problem is.

Then, we run git commit && git push. Since I have configured the ladybug plugin like this:

 1- name: ladybug
 2  ...
 3  - path: issues/**/*.md
 4    branch:
 5    - "*"
 6    when:
 7    - add
 8    - mod
 9    func: []
10    write:
11      git:
12      - path: issues/**/*.md
13        can:
14        - mod
15      web: []
16      exec: []
17      callfunc: []
18    configuration:
19      metadata:
20      - default: autogenerated
21        mandatory: true
22        name: id
23        type: crc16
24      - default: OPEN
25        mandatory: true
26        name: status
27        type: string
28      - default: email@email.com
29        mandatory: false
30        name: user
31        type: string

You can read this configuration as: “For every Markdown file in the issues directory across all branches, if the file doesn’t have these metadata fields, automatically add these default values.”

Now, if you are a Git purist, a server creating commits right on top of yours might sound a bit radical, or even terrifying. But look closely at the write block in the YAML configuration above:

1write:
2  git:
3    - path: issues/**/*.md
4      can:
5        - mod

So, once you push, the server-side plugin does its job, and the next time you run git pull, your local file will automatically look like this:

1---
2id: 1
3user: email@email.com
4status: OPEN
5---
6
7# My title
8
9My description where I can detail what my problem is.

So, What About the Label?

First, we need a file that lists all of these “issues”. That’s exactly why the silo plugin exists. It inspects all files and groups them whenever it finds a matching pattern.

To list all open “issues”, we configure it like this:

 1- name: silo
 2  ...
 3  run:
 4  - path: "**/*"
 5    branch:
 6    - main
 7    when:
 8    - add
 9    - mod
10    - del
11    func: []
12    write:
13      git:
14      - path: boards/*.md
15        can:
16        - add
17        - mod
18        - del
19        - append
20      web: []
21      exec: []
22      callfunc: []
23    configuration:
24      boards:
25        description: All open issues
26        for: issues/*.md
27        format: table
28        paginator: 50
29        selects:
30        - "status: (.*)"
31        - "user: (.*)"
32        sort: select[0]
33        sortOrder: desc
34        tableHeader: "| | status | user |"
35        title: All issues
36        to: boards/issues.md
37        where: "status: OPEN"

You can read this configuration as: “For every file in the main branch, create a board called ‘All issues’ containing links to all files matching status: OPEN. Display them as a table with status and user columns.”

After running git commit && git push && git pull, you will get a new file at boards/issues.md containing something like this:

1# All issues
2
3All open issues
4
5|                                   | status | user            |
6| --------------------------------- | ------ | --------------- |
7| [My title](../issues/my_issue.md) | OPEN   | email@email.com |

Now that we have a page representing all our issues, we can finally render it in the browser. Because, as you might have guessed, the label causing all this debate lives in the Web UI.

The Web is Where It Happens

To render my boards/issues.md file on the web, I use the apex plugin, in conjunction with the apex_markdown plugin, of course.

These plugins take files from git and render them directly in the Web UI. I configure them like this:

 1- name: apex
 2  ...
 3  run:
 4  - path: "**/*"
 5    branch:
 6    - main
 7    when:
 8    - add
 9    - mod
10    - del
11    func: []
12    write:
13      git:
14      - path: "**/*"
15        can:
16        - add
17        - mod
18        - del
19        - append
20      web:
21      - path: "**/*"
22        can:
23        - add
24        - mod
25        - del
26        - append
27      exec: []
28      callfunc:
29      - pluginname: apex_markdown
30        funcname: renderMd
31      ...
32    configuration:
33      ...
34      menu:
35      - display: 🏠 Home
36        link: /
37      - display: 📖 Documentation
38        link: /doc/
39      - display: 🔖 Versions
40        link: /CHANGELOG.html
41      - display: �� Plugins
42        link: /plugins/
43      - display: �� Issues
44        link: /boards/issues.html
45      - display: 🚀 Code
46        link: /worktree/
47      - display: ☕ Blog
48        link: /blog/
49      - display: �� Contact
50        link: /contact.html

If you are wondering how Apex magically knows where to find your “issues”, the secret is: it doesn’t.

Conclusion

I’m pretty sure you now understand why I didn’t immediately jump on resolving this task: everything we just saw is pure configuration, completely separated from the GitRoot core code.

In fact, I personally call them TODOs, because in reality, they are all just waiting for me to get them done.

Wait… Why stop at issues?

This is where the true power of GitRoot will blow your mind.

Yes, you read that right. You can visit it live at https://gitroot.dev/boards/todos.html.

If you want to discover more plugins and configurations, feel free to browse through the 🧩 Plugins section. However, for now, the best way to explore remains checking out the actual GitRoot plugins.yml configuration file.

0.5.0

romain@gitroot.dev (Romain Maneschi) — 2026/10/05

Move slowly, and take care of things

Thanks to lonugem for the title idea

If you only have 5 minutes

Breaking PURL

Joking aside, you need to replace your plugin URL with a PURL one. ECMA PURL is a specification to produce “a standardized URL-based syntax that uniquely identifies software packages”.

This corresponds to the following change:

1- url: https://gitroot.dev/releases/0.4.0/ladybug-0.0.4.wasm
2- checksum: sha256:7409837469ce89d5c9fd8dd48236764650f48523ff4d81295967154977a01635
3- name: ladybug
4- version: 0.0.4
5+ purl: pkg:gitroot/gitroot/ladybug@0.0.5?checksum=none&registry=https:%2F%2F%2Fgitroot.dev%2Freleases%2F0.5.0
6  active: true

Look in the plugins registry to find the exact purl for each plugin.

To know why, how and more read purl details.

A lot of people have discovered GitRoot

First show, first lobste.rs/HN links, first video… Yes, more and more people are talking about GitRoot. Discover where.

Not conclusive

Before it’s too late

My new favorite language…. until the next one

Plugins needs more power

Sftp to save the web

How many bugs?

A lot of bug fixes have been done. Let me explain some interesting ones.

In-depth Details

PURL breaking details

Another example is if someone forks ladybug and wants to release it in the registry. Previously there was no option to do that, so adding a scope seemed to be the best choice.

That was a big refactor to do, but I’m pretty happy with the result.

GitRoot communication

A lot has occured during this summer, on the communication side too.

And GitRoot has been added to AlternativeTo. I don’t know if this will lead to anything, but hey, I’m right alongside GitHub and GitLab :P

SdkGenerator full story

Max anonymous branches

Zig plugin-sdk

PluginSdk improvements

Regarding the plugin-sdk, here are a lot of new capabilities for plugins to use:

schedule: you can allow a plugin to be called at a scheduled time. The format is a cron expression with 5 segments as <minute> <hour> <day> <month> <weekday>. Example:

1- purl: pkg:gitroot/gitroot/firefly@0.0.1?checksum=none&registry=file:%2F%2F%2Fhome%2Frmaneschi%2Fprojects%2Fgitroot%2Fapp%2Ftestsuite%2F..%2Fplugins%2Ffirefly
2  active: true
3  run:
4    - path: ""
5      branch:
6        - main
7      when: []
8      schedule: "* * * * *"

That means the firefly plugin will be executed on the main branch every minute. Refer to the gronx library documentation for cron expression details.

1callFunc:
2  - pluginPURL: pkg:gitroot/gitroot/apex
3    funcName: renderHtml
4    configuration:
5      branchesDir: branches
6      favicon: logo.png
7      footer: <p>Start with <code>git clone ssh://gitroot.dev/</code> ��</p><small>Hosted with ❤️ by Gitroot</small>
8      generateGitWorktree: true
9      header: ...

Sftp feature

Be careful: this feature is in alpha, so don’t write scripts around it for now. I will probably change the directory hierarchy #d42a.

Some interesting bug fixes

What next?

Then I will probably start working on:

Discover GitRoot without installing anything.
Create your own plugins with ease.
Transform GitRoot into a registry for (at least) Go, Rust, NPM and Zig.
Federation with GitRoot but also other forges.
Implement something for users (how to represent them).
Manage more Git functions in plugins (branch, pull, push, rebase).
Use pull-iterators to stabilise the plugin-sdk.
Easier configuration of plugins.
Auto-update of plugins.
New language plugin-sdk.
Air-gapped version of GitRoot.
Make every repository a gemini capsule.

Special thanks to Ryuno-Ki, Matthieu and ks from the #gitroot:matrix.org Matrix room for reviewing and correcting this article. Want to help with future posts? Join us in the room!

0.4.0

rmaneschi@gmail.com (Romain Maneschi) — 2026/04/22

The teenager starts building its own future

If you only have 5 minutes

If you skim this article, don’t forget to check out the conclusion about “what’s next?”.

The thing i’m most proud of

Executors can finally build GitRoot! As I love to say: GitRoot can build GitRoot on GitRoot. And it was a pain to do. Read more.

The thing with the most visibility

The thing that changes everything but was so simple

The thing that was more complex than I thought

The things I’m just happy are done

No more mandatory signed commits! Well, it’s still better if you sign them, but this change means the .gitroot/init.sh has been ~~deleted~~ moved to a plugin. Read more.

In-depth Details

Executor

Still not the end! After that, I needed to configure port numbers, so I built a complete environment variable system, and used it to configure some mise paths.

But hey, let’s celebrate what we’ve built before jumping into the next sprint!

Plugin registry

Apex render branch

Elegant, but honestly, a total over-engineered mess. When I actually sat down to code this, I ended up adding just two lines to the apex plugin:

1if p.currentCommit.Branch != "" && p.currentCommit.Branch != p.config.defaultBranch {
2	path = filepath.Join(p.config.branchesDir, p.currentCommit.Branch, path)
3}

Plugin deps

So, I started building the apex_markdown plugin, then apex_code, and next week apex_mermaid. But what I hadn’t fully anticipated was the sheer amount of work required to make it all work together.

With this in place, I’m not even sure if I’ll keep the report system, which was an other way of passing information between plugins.

Sigma plugin

Now, you have the choice to accept unsigned commits in your repo. You can even ignore the whole signing topic entirely if you don’t install the stigma plugin.

That said, I’m still convinced that signing commits should remain the default.

FS plugin-sdk

I have marked all old methods as deprecated, and they will be removed in the next version of GitRoot (or more specifically, the plugin-sdk, though they share the same release number for now).

What next?

I have a massive roadmap for GitRoot (in no particular order):

Discover GitRoot without installing anything.
Create your own plugins with ease.
Transform GitRoot into a registry for (at least) Go, Rust, and NPM.
Plugins should be usable via PURL.
Plugins can send/receive HTTP requests.
Plugins can be scheduled.
Rebase go-git to take advantage of their performance improvements.
Generate the plugin SDK automatically.
Add plugin SDKs for (at least) Zig, Kotlin, and Python.

This is only the beginning. GitRoot will get better and better with every release.

0.3.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/12/20

From “baby to teenager” GitRoot become a forge

If you only have 5 minutes

To activate this new capability on your instance, follow the administrator section. To start using it as a user, see the user section.

Finally, I discuss Apex and many other tiny but useful things.

In-depth Details

For admin: activating an executor

When you update GitRoot to 0.3.0 a new configuration block will appear in the .gitroot/forgeConfig.yml file of your root repository:

 1execconf:
 2  baremetal:
 3    enabled: false
 4  bwrap:
 5    enabled: false
 6    user: nobody
 7    uid: 65534
 8    gid: 65534
 9    robind: []
10    bind: []
11  container:
12    enabled: false
13    bin: podman
14  ssh:
15    enabled: false
16    hosts:
17      - user: myUSer
18        address: 127.0.0.1
19        port: 22
20        publickey: ssh-ed25519 AAAAC3NzaC1...

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.

Bare Metal: simplest but most dangerous

Bubblewrap (bwrap): lightweight sandboxing

Container: heavyweight but most flexible

GitRoot 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.

SSH: remote execution (alpha)

For user: using the `hop` plugin

To execute a build (or command execution), users must activate the hop plugin and configure its execution rules:

 1- url: /home/rmaneschi/projects/gitroot/app/testsuite/../plugins/hop/hop-0.0.1.wasm
 2  name: hop
 3  version: 0.0.1
 4  active: true
 5  run:
 6    - path: "*"
 7      branch:
 8        - "*"
 9      when:
10        - add
11        - mod
12      write:
13        git: []
14        web: []
15        exec:
16          - command: cat
17      configuration:
18        exec:
19          build: ""
20          cmds:
21            - args:
22                - README.md
23              cmd: cat
24          env: []

Add all desired commands for the plugin to call in run.write.exec.

Then in run.configuration.exec:

set environment variables via env (e.g., "MY_ENV=my_val")
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)
define the commands and arguments to execute under cmds

Plugin api report and reporter

To allow reporting without forcing a communication channel, I’ve created two new plugin APIs.

Report: 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.

Reporter API: after reports are collected, GitRoot calls all plugins that implement the Reporter interface.

GitRoot bets on mise

Communication and community building

Alongside the technical work for v0.3.0, a focused effort was put into non-technical tasks to improve communication with the community.

I also established a direct chat room on matrix, accessible via https://matrix.to/#/#gitroot:matrix.org. Feel free to stop by to ask questions or just say hello.

Apex a better web experience

The Apex plugin receives numerous bug fixes and quality of life improvements:

favicon support: a favicon can now be added via the configuration
styled 404 page: the 404 error page now correctly uses the site’s CSS
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
menu highlighting: the current page in the navigation menu is now highlighted
lightweight template: added some variables in header and footer templates

And others useful updates

Although this article is already quite long, I want to briefly mention several smaller yet important tasks completed in this release.

ForgeConf update

Integrated updater

Rust and WASM

0.2.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/09/18

Version 0.2.0 is here

First contribution

Although all my new contributions were related to “bug fixes”, some of them required new features.

No notification == no contribution

To follow all gitroot commits follow https://gitroot.dev/rss/all-commits.xml

Lot of bugs

Let’s the show continue

No linux == no gitroot

Doc, doc… doc?

A lot more

As you can see, there were many mistakes in the first version. However, they have all been fixed, and, of course, I have added plenty more to keep me busy for the next version!

More technicals bugs

Simplify plugin install

What next?

With the exception of any new bugs detected for the next iteration, I would like to focus on the following:

creating a plugins marketplace
adding a new language SDK for plugins (Maybe Rust? Or Zig?)
rebasing the Git lib fork and applying patches

0.1.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/09/18

GitRoot 0.1.0 is deployed 🎉��

GitRoot in numbers:

58 commits
+500 files https://gitroot.dev/worktree/
1 issue in gitlab (closed) https://gitlab.com/gitroot/gitroot/-/issues/1
29 issues close https://gitroot.dev/boards/closed.html
43 issues open https://gitroot.dev/boards/issues.html
22 pages de doc https://gitroot.dev/doc/
4 licences https://gitroot.dev/README.html#license
4 plugins https://gitroot.dev/CHANGELOG.html#plugins

But if you retain only one, it is:

1 contributor https://gitroot.dev/worktree/.gitroot/users.yml.html (others are forge and plugins 😭)

So there is only one thig to do… read the doc and contribute!

blog/security-vulnerability-1.md

rmaneschi@gmail.com (Romain Maneschi) — 2026/03/30

Security Advisory: Executor Command Injection

1. Executive Summary

Severity: Moderate
Affected Version: 0.3.0
Fix Status: Scheduled for version 0.4.0

2. Technical Details

3. Impact Analysis

The level of risk depends on your infrastructure configuration:

High Risk: Users utilizing bareMetal or ssh executors.
Low Risk: Users utilizing bubblewrap or container isolation (as the sandbox significantly limits the potential impact on the host).

Exploitability Constraints: This vulnerability is not a “remote code execution” flaw in the traditional sense. Exploitation requires:

Installing a malicious plugin.
Having write access to the default branch of the root repository.
Merging a malicious .gitroot/plugins.yml into the default branch.

4. Immediate Mitigations

If you cannot wait for the 0.4.0 release, we recommend applying the following measures:

Disable Executors: Set your forge configuration for executors to None.
Secure Executors: Use more secure executors, such as bwrap or container.
Plugin Trust: Only install and enable plugins from trusted sources.
Access Control: Strictly monitor and review all changes to .gitroot/plugins.yml, specifically focusing on authorized system commands.

5. Patch Schedule

6. Security Contact

Transparency and security are core values at GitRoot. If you discover any other potential vulnerabilities or have questions regarding this report, please contact us directly at contact@gitroot.dev.

Modifying the API in the SDK Plugin

rmaneschi@gmail.com (Romain Maneschi) — 2026/04/06

Modifying the API in the SDK Plugin

The last feature for version 0.4 is about adding mv (move) and cp (copy) functions to the SDK plugin. I’m taking advantage of this development to explain how the plumbing works under the hood.

Right now, the SDK plugin is undocumented because there are a lot of breaking changes coming. Every time I develop a new plugin, I discover better ways to do things, and the SDK needs to adapt.

Anyway, I think explaining how the SDK works through a concrete example will be helpful, if not for you, at least for me.

What is the SDK’s job?

Wait, only integers?

When you build a plugin, you just implement an interface. The SDK handles the rest: you receive objects and strings, and you send back data without ever worrying about the underlying WASM pointers.

What does a concrete implementation look like?

When I add a new function, I always start with the host side. All functions are located in runtime.go.

1r.wazRun.
2    NewFunctionBuilder().WithFunc(r.MoveFileBuilder(false)).Export("moveFile").
3    NewFunctionBuilder().WithFunc(r.MoveFileBuilder(true)).Export("moveFileAS")

Then I implement the builder:

 1func (r *runtime) MoveFileBuilder(forAS bool) interface{} {
 2	if !forAS {
 3		return func(_ context.Context, m api.Module, ptr, size, ptr2, size2 uint32) {
 4			// from ptr/size to string or object
 5			r.moveFile(fromPath, toPath)
 6		}
 7	} else {
 8		return func(_ context.Context, m api.Module, ptr, ptr2 uint32) {
 9			// from ptr to string or object
10			r.moveFile(fromPath, toPath)
11		}
12	}
13}

Yeah, I know. As a Gopher, seeing interface{} as a return type and all these uint32 feels wrong. But hey, we’re not here for a code review, we’re here to add an API. If you have a cleaner way, feel free to submit a graft!

We want to allow any plugin to move a file. Let’s define the internal moveFile function:

1func (r *runtime) moveFile(fromPath, toPath string) error {
2	//need to do something...
3}

1func (r *runtime) moveFile(fromFs, fromPath, toFs, toPath string) error {
2	//need to do something...
3}

Now your plugin can call moveFile("cache", "artifacts/myBin", "web", "releases/myBin-v1.0") to publish an artifact, or moveFile("web", "index.html", "web", "old/index.html") to back up a file.

I won’t bore you with the implementation logic here. If you’re curious, check the code.

Here is how the final builder looks, converting pointers to strings:

 1func (r *runtime) MoveFileBuilder(forAS bool) interface{} {
 2	if !forAS {
 3		return func(_ context.Context, m api.Module, fromFsPtr, fromFsSize, fromPathPtr, fromGlobPathSize, toFsPtr, toFsSize, toPathPtr, toPathSize uint32) uint64 {
 4			fromFs, err := r.readString(m, "MoveFile fromFs", fromFsPtr, fromFsSize)
 5			if err != nil {
 6				return r.sendEmptyOrError(m, err)
 7			}
 8			fromPath, err := r.readString(m, "MoveFile fromGlobPath", fromPathPtr, fromGlobPathSize)
 9			if err != nil {
10				return r.sendEmptyOrError(m, err)
11			}
12			toFs, err := r.readString(m, "MoveFile toFs", toFsPtr, toFsSize)
13			if err != nil {
14				return r.sendEmptyOrError(m, err)
15			}
16			toPath, err := r.readString(m, "MoveFile toPath", toPathPtr, toPathSize)
17			if err != nil {
18				return r.sendEmptyOrError(m, err)
19			}
20			return r.sendEmptyOrError(m, r.moveFile(fromFs, fromPath, toFs, toPath))
21		}
22	} else {
23		return func(_ context.Context, m api.Module, fromFsPtr, fromPathPtr, toFsPtr, toPathPtr uint32) uint64 {
24			fromFs, err := r.readASString(m, "MoveFileAS fromFs", fromFsPtr)
25			if err != nil {
26				return r.sendEmptyOrError(m, err)
27			}
28			fromPath, err := r.readASString(m, "MoveFileAS fromGlobPath", fromPathPtr)
29			if err != nil {
30				return r.sendEmptyOrError(m, err)
31			}
32			toFs, err := r.readASString(m, "MoveFileAS toFs", toFsPtr)
33			if err != nil {
34				return r.sendEmptyOrError(m, err)
35			}
36			toPath, err := r.readASString(m, "MoveFileAS toPath", toPathPtr)
37			if err != nil {
38				return r.sendEmptyOrError(m, err)
39			}
40			return r.sendEmptyOrError(m, r.moveFile(fromFs, fromPath, toFs, toPath))
41		}
42	}
43}

Inside the SDK

In the server interface:

1type Server interface {
2    //...
3    MoveFile(fromFs, fromPath, toFs, toPath string) error
4    //...
5}

To make it more “user-friendly”, I use a struct to represent the filesystem in model/fs.go:

1func (g *GrFs) MoveFile(fromPath string, toPath string) error {
2    return g.server.MoveFile(g.base, fromPath, g.base, toPath)
3}
4
5func (g *GrFs) MoveFileToFs(fromPath string, toFs *GrFs, toPath string) error {
6    return g.server.MoveFile(g.base, fromPath, toFs.base, toPath)
7}

The actual WASM call happens in plugin/server.go, where we transform strings back into pointers:

 1// MoveFile implements [model.ServerNeeded].
 2func (s *pServer) MoveFile(fromFs model.FsBase, fromPath string, toFs model.FsBase, toPath string) error {
 3	ptr, size := stringToPtr(string(fromFs))
 4	ptr2, size2 := stringToPtr(fromPath)
 5	ptr3, size3 := stringToPtr(string(toFs))
 6	ptr4, size4 := stringToPtr(toPath)
 7	resPtrSize := _moveFile(ptr, size, ptr2, size2, ptr3, size3, ptr4, size4)
 8	runtime.KeepAlive(fromFs)
 9	runtime.KeepAlive(fromPath)
10	runtime.KeepAlive(toFs)
11	runtime.KeepAlive(toPath)
12	return ptrSizeToError(resPtrSize)
13}

And finally, the link to the host via go:wasmimport in plugin/imports.go:

1//go:wasmimport gitroot moveFile
2func _moveFile(fromFsPtr, fromFsSize, fromPathPtr, fromPathSize, toFsPtr, toFsSize, toPathPtr, toPathSize uint32) (ptrSize uint64)

How to use it?

Now, any plugin can use this. Here’s a simple Go plugin that triggers a build whenever a .go file is modified and moves the binary to the web folder.

 1package main
 2
 3import (
 4	"fmt"
 5	"path/filepath"
 6	"strings"
 7
 8	gitroot "gitroot.dev/libs/golang/plugin"
 9	"gitroot.dev/libs/golang/plugin/model"
10)
11
12var defaultRun = []model.PluginRun{{
13	Path:   "**/*.go",
14	When:   model.PluginRunWhenAll,
15	Branch: []string{"main"},
16	Write: model.PluginWrite{
17		Web: []model.PluginWriteRight{{
18			Path: "releases/main",
19			Can:  model.PluginWriteRightCanAll,
20		}},
21	},
22}}
23
24type Plugin struct {
25	server model.Server
26    needToBuild bool
27}
28
29func (p *Plugin) Init(repoName string, confHasChanged bool, serializedConf string) error {
30    p.needToBuild = false
31    return nil
32}
33
34func (p *Plugin) StartCommit(commit model.Commit) error                                  { return nil }
35
36func (p *Plugin) AddFile(file model.File) error                                          {
37	p.needToBuild = true
38    return nil
39}
40
41func (p *Plugin) ModFile(file model.File) error                                          {
42	p.needToBuild = true
43    return nil
44}
45
46func (p *Plugin) DelFile(file model.File) error                                          {
47	p.needToBuild = true
48    return nil
49}
50
51func (p *Plugin) EndCommit(commit model.Commit) error                                    { return nil }
52
53func (p *Plugin) Finish() error                                                          {
54    if p.needToBuild {
55        res, _ := p.server.Exec(model.Exec{
56            Cmds: []model.Cmd{
57                {Cmd: "go", Args: []string{"build"}},
58            },
59            Artifacts: []string{"main"},
60        })
61        return p.server.Cache().MoveFileToFs(res.Artifacts[0], p.server.Webcontent(), filepath.Join("releases", "main"))
62	}
63    return nil
64}
65
66func Build(server model.Server) model.Plugin {
67	return &Plugin{
68		server: server,
69	}
70}
71
72//go:wasmexport install
73func main() {
74	gitroot.Register(defaultRun, Build)
75}

Is that all?

Nope. I still need to update the Rust and AssemblyScript SDKs and, of course, add tests. But this should give you a good idea of how the plumbing works.

If anything is unclear, let me know!

Comment contribuer au développement de GitRoot

rmaneschi@gmail.com (Romain Maneschi) — 2025/11/18

Comment contribuer au développement de GitRoot 11-2025

Alors pourquoi pas de contributeurs externes sur GitRoot ?

Pré-requis

Il n’y a pas grand chose à faire pour être prêt à aider sur GitRoot:

vous devez avoir git
git clone ssh://gitroot.dev
cd gitroot.dev
./gitroot/init.sh

Si vous souhaitez coder il vous faudra en plus:

bash et make (si vous êtes dev il y a de grandes chances que vous les aillez déjà)
installer mise, c’est le plus simple pour avoir tous les compilateurs dans les bonnes versions

Avant de commencer

On peut également en parler par mail contact@gitroot.dev ou sur le fediverse ^{[forge@gitrrot.dev]}(https://gts.gitroot.dev/@forge).

Qu’est-ce qu’on peut faire ?

Corriger les fautes

Moi je veux faire du web

Quand vous êtes content faites une branche avec votre css dans apex, puis git add . et git push je m’occupe du reste.

Moi je veux coder

Bien, pas de soucis, voici une liste de petites tâches (enfin elles me paraissent petites mais si c’est pas le cas pour vous dites le moi):

en golang:
- dans le plugin grafter pouvoir afficher autre chose dans le 1er message d’un graft. La bannière est en dure dans le plugin, il faudrait l’exporter dans la conf du plugin et l’utiliser.
- dans le plugin silo permettre de grouper par fichier ou date
- plus difficile mais j’aimerais bien avoir plus de renderer dans apex, par exemple les infos, warning et autre
en typescript:
- dans le plugin pollen il y a un bug sur le rss il est jamais nettoyé. Rajouté une option (ou pas, 100 en dur me semble être déjà pas mal) pour limiter le nombre d’<item>.
- toujours dans le plugin pollen pourquoi pas rajouter un json feed en plus du rss. On peut serializer du json en assemblescript.
- plus difficile mais il serait bien de pouvoir dire au plugin pollen de générer un rss avec le contenu des fichiers. Ça permettrait à GitRoot d’avoir un rss affichant les articles du blog par exemple. Aujourd’hui il ne met dans le rss que les commits.
en rust:
- faire ce que Ygor à dit dans https://floss.social/@ygor/115474535138702961 je ne suis pas un developpeur rust et transformer des String en &str me parle pas beaucoup mais si vous l’êtes je suis sûr que c’est une petite tâche. Le code se trouve dans le plugin sdk et le plugin hop.
- ajouter un fakeServer au plugin sdk pour faciliter les tests d’un plugin, voici celui de go https://gitroot.dev/worktree/app/libs/golang/plugin/test/fakeserver.go.html

Moi je suis sysadmin

Parfait il y a de quoi faire aussi:

aujourd’hui il y a trop d’étapes pour releaser GitRoot, automatiser au maximum m’aiderais beaucoup.
si vous avez un petit de place sur un de vos serveurs, tester de déployer une instance juste pour le fun. Peu être vous pourrez améliorer la doc ou trouver quelque chose qui ne marche plus. Ou ajouter un paragraphe pour utiliser gitroot avec nginx ou autre.

Moi je veux tester

tous les tests sont en bash dans testsuite/runtest.sh se trouve le plus gros test, à côté il y en d’autres
- exécutez les pour voir s’ils marchent chez vous me parait une bonne première tâche
- en créer de nouveaux
- améliorer les existants en sortant par exemple des fonctions helper comme quiet_git(), report() ou mySleep() dans d’autres fichiers (et les importer) serait d’une grande aide pour le projet. Vous pouvez aussi créer des nouveaux pour killGitroot() qui est fait en début de chaque fichier. Ou createProject() qui consiste à chaque fois à aller dans le root repository et ajouter son nom dans le fichier .gitroot/repositories.yml.

Moi je veux juste réfléchir/discutter

Tu es le bienvenue sur le channel gitroot dans matrix. Ou par mail contact [AT] gitroot.dev ou sur le fediverse @forge@gitroot.dev sur ce serveur.

How to help building GitRoot

rmaneschi@gmail.com (Romain Maneschi) — 2025/11/18

How to help building GitRoot 11-2025

This article is the translation of french version thanks to DeepL

So why not have external contributors on GitRoot?

Prerequisites

There isn’t much you need to do to get ready to help out on GitRoot:

you need to have git
git clone ssh://gitroot.dev
cd gitroot.dev
./gitroot/init.sh

If you want to code, you will also need:

bash and make (if you are a developer, chances are you already have them)
Install mise, which is the easiest way to get all the right versions of the compilers

Before we begin

We can also talk about it by email contact@gitroot.dev or on the fediverse ^{[forge@gitrrot.dev]}(https://gts.gitroot.dev/@forge).

What can we do?

Correct mistakes

I want to work on the web

It would be great to create (or find) a theme. GitRoot currently uses simplecss, and it only needs classless CSS. There are many available, but you can also create one for GitRoot.

When you are satisfied, create a branch with your CSS in apex, then git add . and git push. I’ll take care of the rest.

I want to code

Okay, no worries, here’s a list of small tasks (well, they seem small to me, but if that’s not the case for you, let me know):

in golang:
- in the grafter plugin, be able to display something else in the first message of a graft. The banner is hard-coded in the plugin; it would need to be exported to the plugin configuration and used.
- In the silo plugin, allow grouping by file or date
- More difficult, but I would like to have more renderers in apex, for example info, warnings, and others
in typescript:
- in the pollen plugin there is a bug in the RSS feed it is never cleaned up. Added an option (or not, 100 seems fine to me) to limit the number of <item>.
- Still in the pollen plugin, why not add a json feed in addition to the RSS feed? We can serialize json in assemblescript.
- More difficult, but it would be nice to be able to tell the pollen plugin to generate an RSS feed with the contents of the files. This would allow GitRoot to have an RSS feed displaying blog articles, for example. Currently, it only puts commits in the RSS feed.
in Rust:
- Do what Ygor said in https://floss.social/@ygor/115474535138702961 I’m not a Rust developer and converting String to &str doesn’t mean much to me, but if you are, I’m sure it’s a small task. The code can be found in the plugin sdk and the hop plugin.
- Add a fakeServer to the plugin sdk to facilitate plugin testing. Here is the one for Go https://gitroot.dev/worktree/app/libs/golang/plugin/test/fakeserver.go.html

I’m a sysadmin.

Perfect, there’s plenty to do:

Today, there are too many steps to release GitRoot. Automating as much as possible would help me a lot.
If you have a little space on one of your servers, try deploying an instance just for fun. Maybe you can improve the documentation or find something that no longer works. Or add a paragraph on using gitroot with nginx or something else.

I want to test

All tests are in bash in /app/testsuite/. The largest test is located in runtest.sh, along with others.
- Running them to see if they work on your system seems like a good first task to me.
- Creating new ones
- Improving existing ones by, for example, moving helper functions such as quiet_git(), report(), or mySleep() to other files (and importing them) would be a great help to the project. You can also create new ones for killGitroot(), which is done at the beginning of each file. Or createProject(), which consists of going to the root repository each time and adding its name to the .gitroot/repositories.yml file

I just want to think/discuss

You are welcome to join the gitroot channel on Matrix. Or contact us by email at contact [AT] gitroot.dev or on the Fediverse at @forge@gitroot.dev on this server.

Issues, Tickets, Discussions... Call them what you want!

rmaneschi@gmail.com (Romain Maneschi) — 2026/06/08

Issues, Tickets, Discussions… Call them what you want!

Many of you, when checking out https://gitroot.dev, have told me that the 🐞 Issues button shouldn’t be labeled “Issues”, but rather “Tickets” or “Discussions”.

The Original Idea

In traditional forges, an “issue” consists of a title and a description created by a user. We can represent it like this:

Easy, right? Well, how do you represent that in GitRoot using only files? This question was running through my mind for months before I finally found a solution.

The Basic Solution

A simple text format that handles metadata perfectly is Markdown. I use Markdown here, but any other markup language could work. Let’s create a file named issues/1.md:

1---
2id: 1
3user: email@email.com
4status: OPEN
5---
6
7# My title
8
9My description where I can detail what my problem is.

Yes, it really is that simple. In GitRoot, to create an issue, you just create a file, add some metadata, commit, and push. Boom, you have an issue.

A Better Solution

1# My title
2
3My description where I can detail what my problem is.

Then, we run git commit && git push. Since I have configured the ladybug plugin like this:

 1- name: ladybug
 2  ...
 3  - path: issues/**/*.md
 4    branch:
 5    - "*"
 6    when:
 7    - add
 8    - mod
 9    func: []
10    write:
11      git:
12      - path: issues/**/*.md
13        can:
14        - mod
15      web: []
16      exec: []
17      callfunc: []
18    configuration:
19      metadata:
20      - default: autogenerated
21        mandatory: true
22        name: id
23        type: crc16
24      - default: OPEN
25        mandatory: true
26        name: status
27        type: string
28      - default: email@email.com
29        mandatory: false
30        name: user
31        type: string

You can read this configuration as: “For every Markdown file in the issues directory across all branches, if the file doesn’t have these metadata fields, automatically add these default values.”

Now, if you are a Git purist, a server creating commits right on top of yours might sound a bit radical, or even terrifying. But look closely at the write block in the YAML configuration above:

1write:
2  git:
3    - path: issues/**/*.md
4      can:
5        - mod

So, once you push, the server-side plugin does its job, and the next time you run git pull, your local file will automatically look like this:

1---
2id: 1
3user: email@email.com
4status: OPEN
5---
6
7# My title
8
9My description where I can detail what my problem is.

So, What About the Label?

First, we need a file that lists all of these “issues”. That’s exactly why the silo plugin exists. It inspects all files and groups them whenever it finds a matching pattern.

To list all open “issues”, we configure it like this:

 1- name: silo
 2  ...
 3  run:
 4  - path: "**/*"
 5    branch:
 6    - main
 7    when:
 8    - add
 9    - mod
10    - del
11    func: []
12    write:
13      git:
14      - path: boards/*.md
15        can:
16        - add
17        - mod
18        - del
19        - append
20      web: []
21      exec: []
22      callfunc: []
23    configuration:
24      boards:
25        description: All open issues
26        for: issues/*.md
27        format: table
28        paginator: 50
29        selects:
30        - "status: (.*)"
31        - "user: (.*)"
32        sort: select[0]
33        sortOrder: desc
34        tableHeader: "| | status | user |"
35        title: All issues
36        to: boards/issues.md
37        where: "status: OPEN"

You can read this configuration as: “For every file in the main branch, create a board called ‘All issues’ containing links to all files matching status: OPEN. Display them as a table with status and user columns.”

After running git commit && git push && git pull, you will get a new file at boards/issues.md containing something like this:

1# All issues
2
3All open issues
4
5|                                   | status | user            |
6| --------------------------------- | ------ | --------------- |
7| [My title](../issues/my_issue.md) | OPEN   | email@email.com |

Now that we have a page representing all our issues, we can finally render it in the browser. Because, as you might have guessed, the label causing all this debate lives in the Web UI.

The Web is Where It Happens

To render my boards/issues.md file on the web, I use the apex plugin, in conjunction with the apex_markdown plugin, of course.

These plugins take files from git and render them directly in the Web UI. I configure them like this:

 1- name: apex
 2  ...
 3  run:
 4  - path: "**/*"
 5    branch:
 6    - main
 7    when:
 8    - add
 9    - mod
10    - del
11    func: []
12    write:
13      git:
14      - path: "**/*"
15        can:
16        - add
17        - mod
18        - del
19        - append
20      web:
21      - path: "**/*"
22        can:
23        - add
24        - mod
25        - del
26        - append
27      exec: []
28      callfunc:
29      - pluginname: apex_markdown
30        funcname: renderMd
31      ...
32    configuration:
33      ...
34      menu:
35      - display: 🏠 Home
36        link: /
37      - display: 📖 Documentation
38        link: /doc/
39      - display: 🔖 Versions
40        link: /CHANGELOG.html
41      - display: �� Plugins
42        link: /plugins/
43      - display: �� Issues
44        link: /boards/issues.html
45      - display: 🚀 Code
46        link: /worktree/
47      - display: ☕ Blog
48        link: /blog/
49      - display: �� Contact
50        link: /contact.html

If you are wondering how Apex magically knows where to find your “issues”, the secret is: it doesn’t.

Conclusion

I’m pretty sure you now understand why I didn’t immediately jump on resolving this task: everything we just saw is pure configuration, completely separated from the GitRoot core code.

In fact, I personally call them TODOs, because in reality, they are all just waiting for me to get them done.

Wait… Why stop at issues?

This is where the true power of GitRoot will blow your mind.

Yes, you read that right. You can visit it live at https://gitroot.dev/boards/todos.html.

If you want to discover more plugins and configurations, feel free to browse through the 🧩 Plugins section. However, for now, the best way to explore remains checking out the actual GitRoot plugins.yml configuration file.

Issues, Tickets, Discussions... Call them what you want!

silo@gitroot.dev (silo) — 2026/06/08

Issues, Tickets, Discussions… Call them what you want!

Many of you, when checking out https://gitroot.dev, have told me that the 🐞 Issues button shouldn’t be labeled “Issues”, but rather “Tickets” or “Discussions”.

The Original Idea

In traditional forges, an “issue” consists of a title and a description created by a user. We can represent it like this:

Easy, right? Well, how do you represent that in GitRoot using only files? This question was running through my mind for months before I finally found a solution.

The Basic Solution

A simple text format that handles metadata perfectly is Markdown. I use Markdown here, but any other markup language could work. Let’s create a file named issues/1.md:

1---
2id: 1
3user: email@email.com
4status: OPEN
5---
6
7# My title
8
9My description where I can detail what my problem is.

Yes, it really is that simple. In GitRoot, to create an issue, you just create a file, add some metadata, commit, and push. Boom, you have an issue.

A Better Solution

1# My title
2
3My description where I can detail what my problem is.

Then, we run git commit && git push. Since I have configured the ladybug plugin like this:

 1- name: ladybug
 2  ...
 3  - path: issues/**/*.md
 4    branch:
 5    - "*"
 6    when:
 7    - add
 8    - mod
 9    func: []
10    write:
11      git:
12      - path: issues/**/*.md
13        can:
14        - mod
15      web: []
16      exec: []
17      callfunc: []
18    configuration:
19      metadata:
20      - default: autogenerated
21        mandatory: true
22        name: id
23        type: crc16
24      - default: OPEN
25        mandatory: true
26        name: status
27        type: string
28      - default: email@email.com
29        mandatory: false
30        name: user
31        type: string

You can read this configuration as: “For every Markdown file in the issues directory across all branches, if the file doesn’t have these metadata fields, automatically add these default values.”

Now, if you are a Git purist, a server creating commits right on top of yours might sound a bit radical, or even terrifying. But look closely at the write block in the YAML configuration above:

1write:
2  git:
3    - path: issues/**/*.md
4      can:
5        - mod

So, once you push, the server-side plugin does its job, and the next time you run git pull, your local file will automatically look like this:

1---
2id: 1
3user: email@email.com
4status: OPEN
5---
6
7# My title
8
9My description where I can detail what my problem is.

So, What About the Label?

First, we need a file that lists all of these “issues”. That’s exactly why the silo plugin exists. It inspects all files and groups them whenever it finds a matching pattern.

To list all open “issues”, we configure it like this:

 1- name: silo
 2  ...
 3  run:
 4  - path: "**/*"
 5    branch:
 6    - main
 7    when:
 8    - add
 9    - mod
10    - del
11    func: []
12    write:
13      git:
14      - path: boards/*.md
15        can:
16        - add
17        - mod
18        - del
19        - append
20      web: []
21      exec: []
22      callfunc: []
23    configuration:
24      boards:
25        description: All open issues
26        for: issues/*.md
27        format: table
28        paginator: 50
29        selects:
30        - "status: (.*)"
31        - "user: (.*)"
32        sort: select[0]
33        sortOrder: desc
34        tableHeader: "| | status | user |"
35        title: All issues
36        to: boards/issues.md
37        where: "status: OPEN"

You can read this configuration as: “For every file in the main branch, create a board called ‘All issues’ containing links to all files matching status: OPEN. Display them as a table with status and user columns.”

After running git commit && git push && git pull, you will get a new file at boards/issues.md containing something like this:

1# All issues
2
3All open issues
4
5|                                   | status | user            |
6| --------------------------------- | ------ | --------------- |
7| [My title](../issues/my_issue.md) | OPEN   | email@email.com |

Now that we have a page representing all our issues, we can finally render it in the browser. Because, as you might have guessed, the label causing all this debate lives in the Web UI.

The Web is Where It Happens

To render my boards/issues.md file on the web, I use the apex plugin, in conjunction with the apex_markdown plugin, of course.

These plugins take files from git and render them directly in the Web UI. I configure them like this:

 1- name: apex
 2  ...
 3  run:
 4  - path: "**/*"
 5    branch:
 6    - main
 7    when:
 8    - add
 9    - mod
10    - del
11    func: []
12    write:
13      git:
14      - path: "**/*"
15        can:
16        - add
17        - mod
18        - del
19        - append
20      web:
21      - path: "**/*"
22        can:
23        - add
24        - mod
25        - del
26        - append
27      exec: []
28      callfunc:
29      - pluginname: apex_markdown
30        funcname: renderMd
31      ...
32    configuration:
33      ...
34      menu:
35      - display: 🏠 Home
36        link: /
37      - display: 📖 Documentation
38        link: /doc/
39      - display: 🔖 Versions
40        link: /CHANGELOG.html
41      - display: �� Plugins
42        link: /plugins/
43      - display: �� Issues
44        link: /boards/issues.html
45      - display: 🚀 Code
46        link: /worktree/
47      - display: ☕ Blog
48        link: /blog/
49      - display: �� Contact
50        link: /contact.html

If you are wondering how Apex magically knows where to find your “issues”, the secret is: it doesn’t.

Conclusion

I’m pretty sure you now understand why I didn’t immediately jump on resolving this task: everything we just saw is pure configuration, completely separated from the GitRoot core code.

In fact, I personally call them TODOs, because in reality, they are all just waiting for me to get them done.

Wait… Why stop at issues?

This is where the true power of GitRoot will blow your mind.

Yes, you read that right. You can visit it live at https://gitroot.dev/boards/todos.html.

If you want to discover more plugins and configurations, feel free to browse through the 🧩 Plugins section. However, for now, the best way to explore remains checking out the actual GitRoot plugins.yml configuration file.

0.4.0

rmaneschi@gmail.com (Romain Maneschi) — 2026/04/22

The teenager starts building its own future

If you only have 5 minutes

If you skim this article, don’t forget to check out the conclusion about “what’s next?”.

The thing i’m most proud of

Executors can finally build GitRoot! As I love to say: GitRoot can build GitRoot on GitRoot. And it was a pain to do. Read more.

The thing with the most visibility

The thing that changes everything but was so simple

The thing that was more complex than I thought

The things I’m just happy are done

No more mandatory signed commits! Well, it’s still better if you sign them, but this change means the .gitroot/init.sh has been ~~deleted~~ moved to a plugin. Read more.

In-depth Details

Executor

Still not the end! After that, I needed to configure port numbers, so I built a complete environment variable system, and used it to configure some mise paths.

But hey, let’s celebrate what we’ve built before jumping into the next sprint!

Plugin registry

Apex render branch

Elegant, but honestly, a total over-engineered mess. When I actually sat down to code this, I ended up adding just two lines to the apex plugin:

1if p.currentCommit.Branch != "" && p.currentCommit.Branch != p.config.defaultBranch {
2	path = filepath.Join(p.config.branchesDir, p.currentCommit.Branch, path)
3}

Plugin deps

So, I started building the apex_markdown plugin, then apex_code, and next week apex_mermaid. But what I hadn’t fully anticipated was the sheer amount of work required to make it all work together.

With this in place, I’m not even sure if I’ll keep the report system, which was an other way of passing information between plugins.

Sigma plugin

Now, you have the choice to accept unsigned commits in your repo. You can even ignore the whole signing topic entirely if you don’t install the stigma plugin.

That said, I’m still convinced that signing commits should remain the default.

FS plugin-sdk

I have marked all old methods as deprecated, and they will be removed in the next version of GitRoot (or more specifically, the plugin-sdk, though they share the same release number for now).

What next?

I have a massive roadmap for GitRoot (in no particular order):

Discover GitRoot without installing anything.
Create your own plugins with ease.
Transform GitRoot into a registry for (at least) Go, Rust, and NPM.
Plugins should be usable via PURL.
Plugins can send/receive HTTP requests.
Plugins can be scheduled.
Rebase go-git to take advantage of their performance improvements.
Generate the plugin SDK automatically.
Add plugin SDKs for (at least) Zig, Kotlin, and Python.

This is only the beginning. GitRoot will get better and better with every release.

0.3.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/12/20

From “baby to teenager” GitRoot become a forge

If you only have 5 minutes

To activate this new capability on your instance, follow the administrator section. To start using it as a user, see the user section.

Finally, I discuss Apex and many other tiny but useful things.

In-depth Details

For admin: activating an executor

When you update GitRoot to 0.3.0 a new configuration block will appear in the .gitroot/forgeConfig.yml file of your root repository:

 1execconf:
 2  baremetal:
 3    enabled: false
 4  bwrap:
 5    enabled: false
 6    user: nobody
 7    uid: 65534
 8    gid: 65534
 9    robind: []
10    bind: []
11  container:
12    enabled: false
13    bin: podman
14  ssh:
15    enabled: false
16    hosts:
17      - user: myUSer
18        address: 127.0.0.1
19        port: 22
20        publickey: ssh-ed25519 AAAAC3NzaC1...

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.

Bare Metal: simplest but most dangerous

Bubblewrap (bwrap): lightweight sandboxing

Container: heavyweight but most flexible

GitRoot 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.

SSH: remote execution (alpha)

For user: using the `hop` plugin

To execute a build (or command execution), users must activate the hop plugin and configure its execution rules:

 1- url: /home/rmaneschi/projects/gitroot/app/testsuite/../plugins/hop/hop-0.0.1.wasm
 2  name: hop
 3  version: 0.0.1
 4  active: true
 5  run:
 6    - path: "*"
 7      branch:
 8        - "*"
 9      when:
10        - add
11        - mod
12      write:
13        git: []
14        web: []
15        exec:
16          - command: cat
17      configuration:
18        exec:
19          build: ""
20          cmds:
21            - args:
22                - README.md
23              cmd: cat
24          env: []

Add all desired commands for the plugin to call in run.write.exec.

Then in run.configuration.exec:

set environment variables via env (e.g., "MY_ENV=my_val")
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)
define the commands and arguments to execute under cmds

Plugin api report and reporter

To allow reporting without forcing a communication channel, I’ve created two new plugin APIs.

Report: 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.

Reporter API: after reports are collected, GitRoot calls all plugins that implement the Reporter interface.

GitRoot bets on mise

Communication and community building

Alongside the technical work for v0.3.0, a focused effort was put into non-technical tasks to improve communication with the community.

I also established a direct chat room on matrix, accessible via https://matrix.to/#/#gitroot:matrix.org. Feel free to stop by to ask questions or just say hello.

Apex a better web experience

The Apex plugin receives numerous bug fixes and quality of life improvements:

favicon support: a favicon can now be added via the configuration
styled 404 page: the 404 error page now correctly uses the site’s CSS
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
menu highlighting: the current page in the navigation menu is now highlighted
lightweight template: added some variables in header and footer templates

And others useful updates

Although this article is already quite long, I want to briefly mention several smaller yet important tasks completed in this release.

ForgeConf update

Integrated updater

Rust and WASM

0.2.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/09/18

Version 0.2.0 is here

First contribution

Although all my new contributions were related to “bug fixes”, some of them required new features.

No notification == no contribution

To follow all gitroot commits follow https://gitroot.dev/rss/all-commits.xml

Lot of bugs

Let’s the show continue

No linux == no gitroot

Doc, doc… doc?

A lot more

As you can see, there were many mistakes in the first version. However, they have all been fixed, and, of course, I have added plenty more to keep me busy for the next version!

More technicals bugs

Simplify plugin install

What next?

With the exception of any new bugs detected for the next iteration, I would like to focus on the following:

creating a plugins marketplace
adding a new language SDK for plugins (Maybe Rust? Or Zig?)
rebasing the Git lib fork and applying patches

0.1.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/09/18

GitRoot 0.1.0 is deployed 🎉��

GitRoot in numbers:

58 commits
+500 files https://gitroot.dev/worktree/
1 issue in gitlab (closed) https://gitlab.com/gitroot/gitroot/-/issues/1
29 issues close https://gitroot.dev/boards/closed.html
43 issues open https://gitroot.dev/boards/issues.html
22 pages de doc https://gitroot.dev/doc/
4 licences https://gitroot.dev/README.html#license
4 plugins https://gitroot.dev/CHANGELOG.html#plugins

But if you retain only one, it is:

1 contributor https://gitroot.dev/worktree/.gitroot/users.yml.html (others are forge and plugins 😭)

So there is only one thig to do… read the doc and contribute!

blog/security-vulnerability-1.md

rmaneschi@gmail.com (Romain Maneschi) — 2026/03/30

Security Advisory: Executor Command Injection

1. Executive Summary

Severity: Moderate
Affected Version: 0.3.0
Fix Status: Scheduled for version 0.4.0

2. Technical Details

3. Impact Analysis

The level of risk depends on your infrastructure configuration:

High Risk: Users utilizing bareMetal or ssh executors.
Low Risk: Users utilizing bubblewrap or container isolation (as the sandbox significantly limits the potential impact on the host).

Exploitability Constraints: This vulnerability is not a “remote code execution” flaw in the traditional sense. Exploitation requires:

Installing a malicious plugin.
Having write access to the default branch of the root repository.
Merging a malicious .gitroot/plugins.yml into the default branch.

4. Immediate Mitigations

If you cannot wait for the 0.4.0 release, we recommend applying the following measures:

Disable Executors: Set your forge configuration for executors to None.
Secure Executors: Use more secure executors, such as bwrap or container.
Plugin Trust: Only install and enable plugins from trusted sources.
Access Control: Strictly monitor and review all changes to .gitroot/plugins.yml, specifically focusing on authorized system commands.

5. Patch Schedule

6. Security Contact

Transparency and security are core values at GitRoot. If you discover any other potential vulnerabilities or have questions regarding this report, please contact us directly at contact@gitroot.dev.

Modifying the API in the SDK Plugin

rmaneschi@gmail.com (Romain Maneschi) — 2026/04/06

Modifying the API in the SDK Plugin

The last feature for version 0.4 is about adding mv (move) and cp (copy) functions to the SDK plugin. I’m taking advantage of this development to explain how the plumbing works under the hood.

Right now, the SDK plugin is undocumented because there are a lot of breaking changes coming. Every time I develop a new plugin, I discover better ways to do things, and the SDK needs to adapt.

Anyway, I think explaining how the SDK works through a concrete example will be helpful, if not for you, at least for me.

What is the SDK’s job?

Wait, only integers?

When you build a plugin, you just implement an interface. The SDK handles the rest: you receive objects and strings, and you send back data without ever worrying about the underlying WASM pointers.

What does a concrete implementation look like?

When I add a new function, I always start with the host side. All functions are located in runtime.go.

1r.wazRun.
2    NewFunctionBuilder().WithFunc(r.MoveFileBuilder(false)).Export("moveFile").
3    NewFunctionBuilder().WithFunc(r.MoveFileBuilder(true)).Export("moveFileAS")

Then I implement the builder:

 1func (r *runtime) MoveFileBuilder(forAS bool) interface{} {
 2	if !forAS {
 3		return func(_ context.Context, m api.Module, ptr, size, ptr2, size2 uint32) {
 4			// from ptr/size to string or object
 5			r.moveFile(fromPath, toPath)
 6		}
 7	} else {
 8		return func(_ context.Context, m api.Module, ptr, ptr2 uint32) {
 9			// from ptr to string or object
10			r.moveFile(fromPath, toPath)
11		}
12	}
13}

Yeah, I know. As a Gopher, seeing interface{} as a return type and all these uint32 feels wrong. But hey, we’re not here for a code review, we’re here to add an API. If you have a cleaner way, feel free to submit a graft!

We want to allow any plugin to move a file. Let’s define the internal moveFile function:

1func (r *runtime) moveFile(fromPath, toPath string) error {
2	//need to do something...
3}

1func (r *runtime) moveFile(fromFs, fromPath, toFs, toPath string) error {
2	//need to do something...
3}

Now your plugin can call moveFile("cache", "artifacts/myBin", "web", "releases/myBin-v1.0") to publish an artifact, or moveFile("web", "index.html", "web", "old/index.html") to back up a file.

I won’t bore you with the implementation logic here. If you’re curious, check the code.

Here is how the final builder looks, converting pointers to strings:

 1func (r *runtime) MoveFileBuilder(forAS bool) interface{} {
 2	if !forAS {
 3		return func(_ context.Context, m api.Module, fromFsPtr, fromFsSize, fromPathPtr, fromGlobPathSize, toFsPtr, toFsSize, toPathPtr, toPathSize uint32) uint64 {
 4			fromFs, err := r.readString(m, "MoveFile fromFs", fromFsPtr, fromFsSize)
 5			if err != nil {
 6				return r.sendEmptyOrError(m, err)
 7			}
 8			fromPath, err := r.readString(m, "MoveFile fromGlobPath", fromPathPtr, fromGlobPathSize)
 9			if err != nil {
10				return r.sendEmptyOrError(m, err)
11			}
12			toFs, err := r.readString(m, "MoveFile toFs", toFsPtr, toFsSize)
13			if err != nil {
14				return r.sendEmptyOrError(m, err)
15			}
16			toPath, err := r.readString(m, "MoveFile toPath", toPathPtr, toPathSize)
17			if err != nil {
18				return r.sendEmptyOrError(m, err)
19			}
20			return r.sendEmptyOrError(m, r.moveFile(fromFs, fromPath, toFs, toPath))
21		}
22	} else {
23		return func(_ context.Context, m api.Module, fromFsPtr, fromPathPtr, toFsPtr, toPathPtr uint32) uint64 {
24			fromFs, err := r.readASString(m, "MoveFileAS fromFs", fromFsPtr)
25			if err != nil {
26				return r.sendEmptyOrError(m, err)
27			}
28			fromPath, err := r.readASString(m, "MoveFileAS fromGlobPath", fromPathPtr)
29			if err != nil {
30				return r.sendEmptyOrError(m, err)
31			}
32			toFs, err := r.readASString(m, "MoveFileAS toFs", toFsPtr)
33			if err != nil {
34				return r.sendEmptyOrError(m, err)
35			}
36			toPath, err := r.readASString(m, "MoveFileAS toPath", toPathPtr)
37			if err != nil {
38				return r.sendEmptyOrError(m, err)
39			}
40			return r.sendEmptyOrError(m, r.moveFile(fromFs, fromPath, toFs, toPath))
41		}
42	}
43}

Inside the SDK

In the server interface:

1type Server interface {
2    //...
3    MoveFile(fromFs, fromPath, toFs, toPath string) error
4    //...
5}

To make it more “user-friendly”, I use a struct to represent the filesystem in model/fs.go:

1func (g *GrFs) MoveFile(fromPath string, toPath string) error {
2    return g.server.MoveFile(g.base, fromPath, g.base, toPath)
3}
4
5func (g *GrFs) MoveFileToFs(fromPath string, toFs *GrFs, toPath string) error {
6    return g.server.MoveFile(g.base, fromPath, toFs.base, toPath)
7}

The actual WASM call happens in plugin/server.go, where we transform strings back into pointers:

 1// MoveFile implements [model.ServerNeeded].
 2func (s *pServer) MoveFile(fromFs model.FsBase, fromPath string, toFs model.FsBase, toPath string) error {
 3	ptr, size := stringToPtr(string(fromFs))
 4	ptr2, size2 := stringToPtr(fromPath)
 5	ptr3, size3 := stringToPtr(string(toFs))
 6	ptr4, size4 := stringToPtr(toPath)
 7	resPtrSize := _moveFile(ptr, size, ptr2, size2, ptr3, size3, ptr4, size4)
 8	runtime.KeepAlive(fromFs)
 9	runtime.KeepAlive(fromPath)
10	runtime.KeepAlive(toFs)
11	runtime.KeepAlive(toPath)
12	return ptrSizeToError(resPtrSize)
13}

And finally, the link to the host via go:wasmimport in plugin/imports.go:

1//go:wasmimport gitroot moveFile
2func _moveFile(fromFsPtr, fromFsSize, fromPathPtr, fromPathSize, toFsPtr, toFsSize, toPathPtr, toPathSize uint32) (ptrSize uint64)

How to use it?

Now, any plugin can use this. Here’s a simple Go plugin that triggers a build whenever a .go file is modified and moves the binary to the web folder.

 1package main
 2
 3import (
 4	"fmt"
 5	"path/filepath"
 6	"strings"
 7
 8	gitroot "gitroot.dev/libs/golang/plugin"
 9	"gitroot.dev/libs/golang/plugin/model"
10)
11
12var defaultRun = []model.PluginRun{{
13	Path:   "**/*.go",
14	When:   model.PluginRunWhenAll,
15	Branch: []string{"main"},
16	Write: model.PluginWrite{
17		Web: []model.PluginWriteRight{{
18			Path: "releases/main",
19			Can:  model.PluginWriteRightCanAll,
20		}},
21	},
22}}
23
24type Plugin struct {
25	server model.Server
26    needToBuild bool
27}
28
29func (p *Plugin) Init(repoName string, confHasChanged bool, serializedConf string) error {
30    p.needToBuild = false
31    return nil
32}
33
34func (p *Plugin) StartCommit(commit model.Commit) error                                  { return nil }
35
36func (p *Plugin) AddFile(file model.File) error                                          {
37	p.needToBuild = true
38    return nil
39}
40
41func (p *Plugin) ModFile(file model.File) error                                          {
42	p.needToBuild = true
43    return nil
44}
45
46func (p *Plugin) DelFile(file model.File) error                                          {
47	p.needToBuild = true
48    return nil
49}
50
51func (p *Plugin) EndCommit(commit model.Commit) error                                    { return nil }
52
53func (p *Plugin) Finish() error                                                          {
54    if p.needToBuild {
55        res, _ := p.server.Exec(model.Exec{
56            Cmds: []model.Cmd{
57                {Cmd: "go", Args: []string{"build"}},
58            },
59            Artifacts: []string{"main"},
60        })
61        return p.server.Cache().MoveFileToFs(res.Artifacts[0], p.server.Webcontent(), filepath.Join("releases", "main"))
62	}
63    return nil
64}
65
66func Build(server model.Server) model.Plugin {
67	return &Plugin{
68		server: server,
69	}
70}
71
72//go:wasmexport install
73func main() {
74	gitroot.Register(defaultRun, Build)
75}

Is that all?

Nope. I still need to update the Rust and AssemblyScript SDKs and, of course, add tests. But this should give you a good idea of how the plumbing works.

If anything is unclear, let me know!

Comment contribuer au développement de GitRoot

rmaneschi@gmail.com (Romain Maneschi) — 2025/11/18

Comment contribuer au développement de GitRoot 11-2025

Alors pourquoi pas de contributeurs externes sur GitRoot ?

Pré-requis

Il n’y a pas grand chose à faire pour être prêt à aider sur GitRoot:

vous devez avoir git
git clone ssh://gitroot.dev
cd gitroot.dev
./gitroot/init.sh

Si vous souhaitez coder il vous faudra en plus:

bash et make (si vous êtes dev il y a de grandes chances que vous les aillez déjà)
installer mise, c’est le plus simple pour avoir tous les compilateurs dans les bonnes versions

Avant de commencer

On peut également en parler par mail contact@gitroot.dev ou sur le fediverse ^{[forge@gitrrot.dev]}(https://gts.gitroot.dev/@forge).

Qu’est-ce qu’on peut faire ?

Corriger les fautes

Moi je veux faire du web

Quand vous êtes content faites une branche avec votre css dans apex, puis git add . et git push je m’occupe du reste.

Moi je veux coder

Bien, pas de soucis, voici une liste de petites tâches (enfin elles me paraissent petites mais si c’est pas le cas pour vous dites le moi):

en golang:
- dans le plugin grafter pouvoir afficher autre chose dans le 1er message d’un graft. La bannière est en dure dans le plugin, il faudrait l’exporter dans la conf du plugin et l’utiliser.
- dans le plugin silo permettre de grouper par fichier ou date
- plus difficile mais j’aimerais bien avoir plus de renderer dans apex, par exemple les infos, warning et autre
en typescript:
- dans le plugin pollen il y a un bug sur le rss il est jamais nettoyé. Rajouté une option (ou pas, 100 en dur me semble être déjà pas mal) pour limiter le nombre d’<item>.
- toujours dans le plugin pollen pourquoi pas rajouter un json feed en plus du rss. On peut serializer du json en assemblescript.
- plus difficile mais il serait bien de pouvoir dire au plugin pollen de générer un rss avec le contenu des fichiers. Ça permettrait à GitRoot d’avoir un rss affichant les articles du blog par exemple. Aujourd’hui il ne met dans le rss que les commits.
en rust:
- faire ce que Ygor à dit dans https://floss.social/@ygor/115474535138702961 je ne suis pas un developpeur rust et transformer des String en &str me parle pas beaucoup mais si vous l’êtes je suis sûr que c’est une petite tâche. Le code se trouve dans le plugin sdk et le plugin hop.
- ajouter un fakeServer au plugin sdk pour faciliter les tests d’un plugin, voici celui de go https://gitroot.dev/worktree/app/libs/golang/plugin/test/fakeserver.go.html

Moi je suis sysadmin

Parfait il y a de quoi faire aussi:

aujourd’hui il y a trop d’étapes pour releaser GitRoot, automatiser au maximum m’aiderais beaucoup.
si vous avez un petit de place sur un de vos serveurs, tester de déployer une instance juste pour le fun. Peu être vous pourrez améliorer la doc ou trouver quelque chose qui ne marche plus. Ou ajouter un paragraphe pour utiliser gitroot avec nginx ou autre.

Moi je veux tester

tous les tests sont en bash dans testsuite/runtest.sh se trouve le plus gros test, à côté il y en d’autres
- exécutez les pour voir s’ils marchent chez vous me parait une bonne première tâche
- en créer de nouveaux
- améliorer les existants en sortant par exemple des fonctions helper comme quiet_git(), report() ou mySleep() dans d’autres fichiers (et les importer) serait d’une grande aide pour le projet. Vous pouvez aussi créer des nouveaux pour killGitroot() qui est fait en début de chaque fichier. Ou createProject() qui consiste à chaque fois à aller dans le root repository et ajouter son nom dans le fichier .gitroot/repositories.yml.

Moi je veux juste réfléchir/discutter

Tu es le bienvenue sur le channel gitroot dans matrix. Ou par mail contact [AT] gitroot.dev ou sur le fediverse @forge@gitroot.dev sur ce serveur.

How to help building GitRoot

rmaneschi@gmail.com (Romain Maneschi) — 2025/11/18

How to help building GitRoot 11-2025

This article is the translation of french version thanks to DeepL

So why not have external contributors on GitRoot?

Prerequisites

There isn’t much you need to do to get ready to help out on GitRoot:

you need to have git
git clone ssh://gitroot.dev
cd gitroot.dev
./gitroot/init.sh

If you want to code, you will also need:

bash and make (if you are a developer, chances are you already have them)
Install mise, which is the easiest way to get all the right versions of the compilers

Before we begin

We can also talk about it by email contact@gitroot.dev or on the fediverse ^{[forge@gitrrot.dev]}(https://gts.gitroot.dev/@forge).

What can we do?

Correct mistakes

I want to work on the web

It would be great to create (or find) a theme. GitRoot currently uses simplecss, and it only needs classless CSS. There are many available, but you can also create one for GitRoot.

When you are satisfied, create a branch with your CSS in apex, then git add . and git push. I’ll take care of the rest.

I want to code

Okay, no worries, here’s a list of small tasks (well, they seem small to me, but if that’s not the case for you, let me know):

in golang:
- in the grafter plugin, be able to display something else in the first message of a graft. The banner is hard-coded in the plugin; it would need to be exported to the plugin configuration and used.
- In the silo plugin, allow grouping by file or date
- More difficult, but I would like to have more renderers in apex, for example info, warnings, and others
in typescript:
- in the pollen plugin there is a bug in the RSS feed it is never cleaned up. Added an option (or not, 100 seems fine to me) to limit the number of <item>.
- Still in the pollen plugin, why not add a json feed in addition to the RSS feed? We can serialize json in assemblescript.
- More difficult, but it would be nice to be able to tell the pollen plugin to generate an RSS feed with the contents of the files. This would allow GitRoot to have an RSS feed displaying blog articles, for example. Currently, it only puts commits in the RSS feed.
in Rust:
- Do what Ygor said in https://floss.social/@ygor/115474535138702961 I’m not a Rust developer and converting String to &str doesn’t mean much to me, but if you are, I’m sure it’s a small task. The code can be found in the plugin sdk and the hop plugin.
- Add a fakeServer to the plugin sdk to facilitate plugin testing. Here is the one for Go https://gitroot.dev/worktree/app/libs/golang/plugin/test/fakeserver.go.html

I’m a sysadmin.

Perfect, there’s plenty to do:

Today, there are too many steps to release GitRoot. Automating as much as possible would help me a lot.
If you have a little space on one of your servers, try deploying an instance just for fun. Maybe you can improve the documentation or find something that no longer works. Or add a paragraph on using gitroot with nginx or something else.

I want to test

All tests are in bash in /app/testsuite/. The largest test is located in runtest.sh, along with others.
- Running them to see if they work on your system seems like a good first task to me.
- Creating new ones
- Improving existing ones by, for example, moving helper functions such as quiet_git(), report(), or mySleep() to other files (and importing them) would be a great help to the project. You can also create new ones for killGitroot(), which is done at the beginning of each file. Or createProject(), which consists of going to the root repository each time and adding its name to the .gitroot/repositories.yml file

I just want to think/discuss

You are welcome to join the gitroot channel on Matrix. Or contact us by email at contact [AT] gitroot.dev or on the Fediverse at @forge@gitroot.dev on this server.

Issues, Tickets, Discussions... Call them what you want!

rmaneschi@gmail.com (Romain Maneschi) — 2026/06/08

Issues, Tickets, Discussions… Call them what you want!

Many of you, when checking out https://gitroot.dev, have told me that the 🐞 Issues button shouldn’t be labeled “Issues”, but rather “Tickets” or “Discussions”.

The Original Idea

In traditional forges, an “issue” consists of a title and a description created by a user. We can represent it like this:

Easy, right? Well, how do you represent that in GitRoot using only files? This question was running through my mind for months before I finally found a solution.

The Basic Solution

A simple text format that handles metadata perfectly is Markdown. I use Markdown here, but any other markup language could work. Let’s create a file named issues/1.md:

1---
2id: 1
3user: email@email.com
4status: OPEN
5---
6
7# My title
8
9My description where I can detail what my problem is.

Yes, it really is that simple. In GitRoot, to create an issue, you just create a file, add some metadata, commit, and push. Boom, you have an issue.

A Better Solution

1# My title
2
3My description where I can detail what my problem is.

Then, we run git commit && git push. Since I have configured the ladybug plugin like this:

 1- name: ladybug
 2  ...
 3  - path: issues/**/*.md
 4    branch:
 5    - "*"
 6    when:
 7    - add
 8    - mod
 9    func: []
10    write:
11      git:
12      - path: issues/**/*.md
13        can:
14        - mod
15      web: []
16      exec: []
17      callfunc: []
18    configuration:
19      metadata:
20      - default: autogenerated
21        mandatory: true
22        name: id
23        type: crc16
24      - default: OPEN
25        mandatory: true
26        name: status
27        type: string
28      - default: email@email.com
29        mandatory: false
30        name: user
31        type: string

You can read this configuration as: “For every Markdown file in the issues directory across all branches, if the file doesn’t have these metadata fields, automatically add these default values.”

Now, if you are a Git purist, a server creating commits right on top of yours might sound a bit radical, or even terrifying. But look closely at the write block in the YAML configuration above:

1write:
2  git:
3    - path: issues/**/*.md
4      can:
5        - mod

So, once you push, the server-side plugin does its job, and the next time you run git pull, your local file will automatically look like this:

1---
2id: 1
3user: email@email.com
4status: OPEN
5---
6
7# My title
8
9My description where I can detail what my problem is.

So, What About the Label?

First, we need a file that lists all of these “issues”. That’s exactly why the silo plugin exists. It inspects all files and groups them whenever it finds a matching pattern.

To list all open “issues”, we configure it like this:

 1- name: silo
 2  ...
 3  run:
 4  - path: "**/*"
 5    branch:
 6    - main
 7    when:
 8    - add
 9    - mod
10    - del
11    func: []
12    write:
13      git:
14      - path: boards/*.md
15        can:
16        - add
17        - mod
18        - del
19        - append
20      web: []
21      exec: []
22      callfunc: []
23    configuration:
24      boards:
25        description: All open issues
26        for: issues/*.md
27        format: table
28        paginator: 50
29        selects:
30        - "status: (.*)"
31        - "user: (.*)"
32        sort: select[0]
33        sortOrder: desc
34        tableHeader: "| | status | user |"
35        title: All issues
36        to: boards/issues.md
37        where: "status: OPEN"

You can read this configuration as: “For every file in the main branch, create a board called ‘All issues’ containing links to all files matching status: OPEN. Display them as a table with status and user columns.”

After running git commit && git push && git pull, you will get a new file at boards/issues.md containing something like this:

1# All issues
2
3All open issues
4
5|                                   | status | user            |
6| --------------------------------- | ------ | --------------- |
7| [My title](../issues/my_issue.md) | OPEN   | email@email.com |

Now that we have a page representing all our issues, we can finally render it in the browser. Because, as you might have guessed, the label causing all this debate lives in the Web UI.

The Web is Where It Happens

To render my boards/issues.md file on the web, I use the apex plugin, in conjunction with the apex_markdown plugin, of course.

These plugins take files from git and render them directly in the Web UI. I configure them like this:

 1- name: apex
 2  ...
 3  run:
 4  - path: "**/*"
 5    branch:
 6    - main
 7    when:
 8    - add
 9    - mod
10    - del
11    func: []
12    write:
13      git:
14      - path: "**/*"
15        can:
16        - add
17        - mod
18        - del
19        - append
20      web:
21      - path: "**/*"
22        can:
23        - add
24        - mod
25        - del
26        - append
27      exec: []
28      callfunc:
29      - pluginname: apex_markdown
30        funcname: renderMd
31      ...
32    configuration:
33      ...
34      menu:
35      - display: 🏠 Home
36        link: /
37      - display: 📖 Documentation
38        link: /doc/
39      - display: 🔖 Versions
40        link: /CHANGELOG.html
41      - display: �� Plugins
42        link: /plugins/
43      - display: �� Issues
44        link: /boards/issues.html
45      - display: 🚀 Code
46        link: /worktree/
47      - display: ☕ Blog
48        link: /blog/
49      - display: �� Contact
50        link: /contact.html

If you are wondering how Apex magically knows where to find your “issues”, the secret is: it doesn’t.

Conclusion

I’m pretty sure you now understand why I didn’t immediately jump on resolving this task: everything we just saw is pure configuration, completely separated from the GitRoot core code.

In fact, I personally call them TODOs, because in reality, they are all just waiting for me to get them done.

Wait… Why stop at issues?

This is where the true power of GitRoot will blow your mind.

Yes, you read that right. You can visit it live at https://gitroot.dev/boards/todos.html.

If you want to discover more plugins and configurations, feel free to browse through the 🧩 Plugins section. However, for now, the best way to explore remains checking out the actual GitRoot plugins.yml configuration file.

0.4.0

rmaneschi@gmail.com (Romain Maneschi) — 2026/04/22

The teenager starts building its own future

If you only have 5 minutes

If you skim this article, don’t forget to check out the conclusion about “what’s next?”.

The thing i’m most proud of

Executors can finally build GitRoot! As I love to say: GitRoot can build GitRoot on GitRoot. And it was a pain to do. Read more.

The thing with the most visibility

The thing that changes everything but was so simple

The thing that was more complex than I thought

The things I’m just happy are done

No more mandatory signed commits! Well, it’s still better if you sign them, but this change means the .gitroot/init.sh has been ~~deleted~~ moved to a plugin. Read more.

In-depth Details

Executor

Still not the end! After that, I needed to configure port numbers, so I built a complete environment variable system, and used it to configure some mise paths.

But hey, let’s celebrate what we’ve built before jumping into the next sprint!

Plugin registry

Apex render branch

Elegant, but honestly, a total over-engineered mess. When I actually sat down to code this, I ended up adding just two lines to the apex plugin:

1if p.currentCommit.Branch != "" && p.currentCommit.Branch != p.config.defaultBranch {
2	path = filepath.Join(p.config.branchesDir, p.currentCommit.Branch, path)
3}

Plugin deps

So, I started building the apex_markdown plugin, then apex_code, and next week apex_mermaid. But what I hadn’t fully anticipated was the sheer amount of work required to make it all work together.

With this in place, I’m not even sure if I’ll keep the report system, which was an other way of passing information between plugins.

Sigma plugin

Now, you have the choice to accept unsigned commits in your repo. You can even ignore the whole signing topic entirely if you don’t install the stigma plugin.

That said, I’m still convinced that signing commits should remain the default.

FS plugin-sdk

I have marked all old methods as deprecated, and they will be removed in the next version of GitRoot (or more specifically, the plugin-sdk, though they share the same release number for now).

What next?

I have a massive roadmap for GitRoot (in no particular order):

Discover GitRoot without installing anything.
Create your own plugins with ease.
Transform GitRoot into a registry for (at least) Go, Rust, and NPM.
Plugins should be usable via PURL.
Plugins can send/receive HTTP requests.
Plugins can be scheduled.
Rebase go-git to take advantage of their performance improvements.
Generate the plugin SDK automatically.
Add plugin SDKs for (at least) Zig, Kotlin, and Python.

This is only the beginning. GitRoot will get better and better with every release.

0.3.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/12/20

From “baby to teenager” GitRoot become a forge

If you only have 5 minutes

To activate this new capability on your instance, follow the administrator section. To start using it as a user, see the user section.

Finally, I discuss Apex and many other tiny but useful things.

In-depth Details

For admin: activating an executor

When you update GitRoot to 0.3.0 a new configuration block will appear in the .gitroot/forgeConfig.yml file of your root repository:

 1execconf:
 2  baremetal:
 3    enabled: false
 4  bwrap:
 5    enabled: false
 6    user: nobody
 7    uid: 65534
 8    gid: 65534
 9    robind: []
10    bind: []
11  container:
12    enabled: false
13    bin: podman
14  ssh:
15    enabled: false
16    hosts:
17      - user: myUSer
18        address: 127.0.0.1
19        port: 22
20        publickey: ssh-ed25519 AAAAC3NzaC1...

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.

Bare Metal: simplest but most dangerous

Bubblewrap (bwrap): lightweight sandboxing

Container: heavyweight but most flexible

GitRoot 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.

SSH: remote execution (alpha)

For user: using the `hop` plugin

To execute a build (or command execution), users must activate the hop plugin and configure its execution rules:

 1- url: /home/rmaneschi/projects/gitroot/app/testsuite/../plugins/hop/hop-0.0.1.wasm
 2  name: hop
 3  version: 0.0.1
 4  active: true
 5  run:
 6    - path: "*"
 7      branch:
 8        - "*"
 9      when:
10        - add
11        - mod
12      write:
13        git: []
14        web: []
15        exec:
16          - command: cat
17      configuration:
18        exec:
19          build: ""
20          cmds:
21            - args:
22                - README.md
23              cmd: cat
24          env: []

Add all desired commands for the plugin to call in run.write.exec.

Then in run.configuration.exec:

set environment variables via env (e.g., "MY_ENV=my_val")
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)
define the commands and arguments to execute under cmds

Plugin api report and reporter

To allow reporting without forcing a communication channel, I’ve created two new plugin APIs.

Report: 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.

Reporter API: after reports are collected, GitRoot calls all plugins that implement the Reporter interface.

GitRoot bets on mise

Communication and community building

Alongside the technical work for v0.3.0, a focused effort was put into non-technical tasks to improve communication with the community.

I also established a direct chat room on matrix, accessible via https://matrix.to/#/#gitroot:matrix.org. Feel free to stop by to ask questions or just say hello.

Apex a better web experience

The Apex plugin receives numerous bug fixes and quality of life improvements:

favicon support: a favicon can now be added via the configuration
styled 404 page: the 404 error page now correctly uses the site’s CSS
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
menu highlighting: the current page in the navigation menu is now highlighted
lightweight template: added some variables in header and footer templates

And others useful updates

Although this article is already quite long, I want to briefly mention several smaller yet important tasks completed in this release.

ForgeConf update

Integrated updater

Rust and WASM

0.2.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/09/18

Version 0.2.0 is here

First contribution

Although all my new contributions were related to “bug fixes”, some of them required new features.

No notification == no contribution

To follow all gitroot commits follow https://gitroot.dev/rss/all-commits.xml

Lot of bugs

Let’s the show continue

No linux == no gitroot

Doc, doc… doc?

A lot more

As you can see, there were many mistakes in the first version. However, they have all been fixed, and, of course, I have added plenty more to keep me busy for the next version!

More technicals bugs

Simplify plugin install

What next?

With the exception of any new bugs detected for the next iteration, I would like to focus on the following:

creating a plugins marketplace
adding a new language SDK for plugins (Maybe Rust? Or Zig?)
rebasing the Git lib fork and applying patches

0.1.0

rmaneschi@gmail.com (Romain Maneschi) — 2025/09/18

GitRoot 0.1.0 is deployed 🎉��

GitRoot in numbers:

58 commits
+500 files https://gitroot.dev/worktree/
1 issue in gitlab (closed) https://gitlab.com/gitroot/gitroot/-/issues/1
29 issues close https://gitroot.dev/boards/closed.html
43 issues open https://gitroot.dev/boards/issues.html
22 pages de doc https://gitroot.dev/doc/
4 licences https://gitroot.dev/README.html#license
4 plugins https://gitroot.dev/CHANGELOG.html#plugins

But if you retain only one, it is:

1 contributor https://gitroot.dev/worktree/.gitroot/users.yml.html (others are forge and plugins 😭)

So there is only one thig to do… read the doc and contribute!

blog/security-vulnerability-1.md

rmaneschi@gmail.com (Romain Maneschi) — 2026/03/30

Security Advisory: Executor Command Injection

1. Executive Summary

Severity: Moderate
Affected Version: 0.3.0
Fix Status: Scheduled for version 0.4.0

2. Technical Details

3. Impact Analysis

The level of risk depends on your infrastructure configuration:

High Risk: Users utilizing bareMetal or ssh executors.
Low Risk: Users utilizing bubblewrap or container isolation (as the sandbox significantly limits the potential impact on the host).

Exploitability Constraints: This vulnerability is not a “remote code execution” flaw in the traditional sense. Exploitation requires:

Installing a malicious plugin.
Having write access to the default branch of the root repository.
Merging a malicious .gitroot/plugins.yml into the default branch.

4. Immediate Mitigations

If you cannot wait for the 0.4.0 release, we recommend applying the following measures:

Disable Executors: Set your forge configuration for executors to None.
Secure Executors: Use more secure executors, such as bwrap or container.
Plugin Trust: Only install and enable plugins from trusted sources.
Access Control: Strictly monitor and review all changes to .gitroot/plugins.yml, specifically focusing on authorized system commands.

5. Patch Schedule

6. Security Contact

Transparency and security are core values at GitRoot. If you discover any other potential vulnerabilities or have questions regarding this report, please contact us directly at contact@gitroot.dev.

Modifying the API in the SDK Plugin

rmaneschi@gmail.com (Romain Maneschi) — 2026/04/06

Modifying the API in the SDK Plugin

The last feature for version 0.4 is about adding mv (move) and cp (copy) functions to the SDK plugin. I’m taking advantage of this development to explain how the plumbing works under the hood.

Right now, the SDK plugin is undocumented because there are a lot of breaking changes coming. Every time I develop a new plugin, I discover better ways to do things, and the SDK needs to adapt.

Anyway, I think explaining how the SDK works through a concrete example will be helpful, if not for you, at least for me.

What is the SDK’s job?

Wait, only integers?

When you build a plugin, you just implement an interface. The SDK handles the rest: you receive objects and strings, and you send back data without ever worrying about the underlying WASM pointers.

What does a concrete implementation look like?

When I add a new function, I always start with the host side. All functions are located in runtime.go.

1r.wazRun.
2    NewFunctionBuilder().WithFunc(r.MoveFileBuilder(false)).Export("moveFile").
3    NewFunctionBuilder().WithFunc(r.MoveFileBuilder(true)).Export("moveFileAS")

Then I implement the builder:

 1func (r *runtime) MoveFileBuilder(forAS bool) interface{} {
 2	if !forAS {
 3		return func(_ context.Context, m api.Module, ptr, size, ptr2, size2 uint32) {
 4			// from ptr/size to string or object
 5			r.moveFile(fromPath, toPath)
 6		}
 7	} else {
 8		return func(_ context.Context, m api.Module, ptr, ptr2 uint32) {
 9			// from ptr to string or object
10			r.moveFile(fromPath, toPath)
11		}
12	}
13}

Yeah, I know. As a Gopher, seeing interface{} as a return type and all these uint32 feels wrong. But hey, we’re not here for a code review, we’re here to add an API. If you have a cleaner way, feel free to submit a graft!

We want to allow any plugin to move a file. Let’s define the internal moveFile function:

1func (r *runtime) moveFile(fromPath, toPath string) error {
2	//need to do something...
3}

1func (r *runtime) moveFile(fromFs, fromPath, toFs, toPath string) error {
2	//need to do something...
3}

Now your plugin can call moveFile("cache", "artifacts/myBin", "web", "releases/myBin-v1.0") to publish an artifact, or moveFile("web", "index.html", "web", "old/index.html") to back up a file.

I won’t bore you with the implementation logic here. If you’re curious, check the code.

Here is how the final builder looks, converting pointers to strings:

 1func (r *runtime) MoveFileBuilder(forAS bool) interface{} {
 2	if !forAS {
 3		return func(_ context.Context, m api.Module, fromFsPtr, fromFsSize, fromPathPtr, fromGlobPathSize, toFsPtr, toFsSize, toPathPtr, toPathSize uint32) uint64 {
 4			fromFs, err := r.readString(m, "MoveFile fromFs", fromFsPtr, fromFsSize)
 5			if err != nil {
 6				return r.sendEmptyOrError(m, err)
 7			}
 8			fromPath, err := r.readString(m, "MoveFile fromGlobPath", fromPathPtr, fromGlobPathSize)
 9			if err != nil {
10				return r.sendEmptyOrError(m, err)
11			}
12			toFs, err := r.readString(m, "MoveFile toFs", toFsPtr, toFsSize)
13			if err != nil {
14				return r.sendEmptyOrError(m, err)
15			}
16			toPath, err := r.readString(m, "MoveFile toPath", toPathPtr, toPathSize)
17			if err != nil {
18				return r.sendEmptyOrError(m, err)
19			}
20			return r.sendEmptyOrError(m, r.moveFile(fromFs, fromPath, toFs, toPath))
21		}
22	} else {
23		return func(_ context.Context, m api.Module, fromFsPtr, fromPathPtr, toFsPtr, toPathPtr uint32) uint64 {
24			fromFs, err := r.readASString(m, "MoveFileAS fromFs", fromFsPtr)
25			if err != nil {
26				return r.sendEmptyOrError(m, err)
27			}
28			fromPath, err := r.readASString(m, "MoveFileAS fromGlobPath", fromPathPtr)
29			if err != nil {
30				return r.sendEmptyOrError(m, err)
31			}
32			toFs, err := r.readASString(m, "MoveFileAS toFs", toFsPtr)
33			if err != nil {
34				return r.sendEmptyOrError(m, err)
35			}
36			toPath, err := r.readASString(m, "MoveFileAS toPath", toPathPtr)
37			if err != nil {
38				return r.sendEmptyOrError(m, err)
39			}
40			return r.sendEmptyOrError(m, r.moveFile(fromFs, fromPath, toFs, toPath))
41		}
42	}
43}

Inside the SDK

In the server interface:

1type Server interface {
2    //...
3    MoveFile(fromFs, fromPath, toFs, toPath string) error
4    //...
5}

To make it more “user-friendly”, I use a struct to represent the filesystem in model/fs.go:

1func (g *GrFs) MoveFile(fromPath string, toPath string) error {
2    return g.server.MoveFile(g.base, fromPath, g.base, toPath)
3}
4
5func (g *GrFs) MoveFileToFs(fromPath string, toFs *GrFs, toPath string) error {
6    return g.server.MoveFile(g.base, fromPath, toFs.base, toPath)
7}

The actual WASM call happens in plugin/server.go, where we transform strings back into pointers:

 1// MoveFile implements [model.ServerNeeded].
 2func (s *pServer) MoveFile(fromFs model.FsBase, fromPath string, toFs model.FsBase, toPath string) error {
 3	ptr, size := stringToPtr(string(fromFs))
 4	ptr2, size2 := stringToPtr(fromPath)
 5	ptr3, size3 := stringToPtr(string(toFs))
 6	ptr4, size4 := stringToPtr(toPath)
 7	resPtrSize := _moveFile(ptr, size, ptr2, size2, ptr3, size3, ptr4, size4)
 8	runtime.KeepAlive(fromFs)
 9	runtime.KeepAlive(fromPath)
10	runtime.KeepAlive(toFs)
11	runtime.KeepAlive(toPath)
12	return ptrSizeToError(resPtrSize)
13}

And finally, the link to the host via go:wasmimport in plugin/imports.go:

1//go:wasmimport gitroot moveFile
2func _moveFile(fromFsPtr, fromFsSize, fromPathPtr, fromPathSize, toFsPtr, toFsSize, toPathPtr, toPathSize uint32) (ptrSize uint64)

How to use it?

Now, any plugin can use this. Here’s a simple Go plugin that triggers a build whenever a .go file is modified and moves the binary to the web folder.

 1package main
 2
 3import (
 4	"fmt"
 5	"path/filepath"
 6	"strings"
 7
 8	gitroot "gitroot.dev/libs/golang/plugin"
 9	"gitroot.dev/libs/golang/plugin/model"
10)
11
12var defaultRun = []model.PluginRun{{
13	Path:   "**/*.go",
14	When:   model.PluginRunWhenAll,
15	Branch: []string{"main"},
16	Write: model.PluginWrite{
17		Web: []model.PluginWriteRight{{
18			Path: "releases/main",
19			Can:  model.PluginWriteRightCanAll,
20		}},
21	},
22}}
23
24type Plugin struct {
25	server model.Server
26    needToBuild bool
27}
28
29func (p *Plugin) Init(repoName string, confHasChanged bool, serializedConf string) error {
30    p.needToBuild = false
31    return nil
32}
33
34func (p *Plugin) StartCommit(commit model.Commit) error                                  { return nil }
35
36func (p *Plugin) AddFile(file model.File) error                                          {
37	p.needToBuild = true
38    return nil
39}
40
41func (p *Plugin) ModFile(file model.File) error                                          {
42	p.needToBuild = true
43    return nil
44}
45
46func (p *Plugin) DelFile(file model.File) error                                          {
47	p.needToBuild = true
48    return nil
49}
50
51func (p *Plugin) EndCommit(commit model.Commit) error                                    { return nil }
52
53func (p *Plugin) Finish() error                                                          {
54    if p.needToBuild {
55        res, _ := p.server.Exec(model.Exec{
56            Cmds: []model.Cmd{
57                {Cmd: "go", Args: []string{"build"}},
58            },
59            Artifacts: []string{"main"},
60        })
61        return p.server.Cache().MoveFileToFs(res.Artifacts[0], p.server.Webcontent(), filepath.Join("releases", "main"))
62	}
63    return nil
64}
65
66func Build(server model.Server) model.Plugin {
67	return &Plugin{
68		server: server,
69	}
70}
71
72//go:wasmexport install
73func main() {
74	gitroot.Register(defaultRun, Build)
75}

Is that all?

Nope. I still need to update the Rust and AssemblyScript SDKs and, of course, add tests. But this should give you a good idea of how the plumbing works.

If anything is unclear, let me know!

Comment contribuer au développement de GitRoot

rmaneschi@gmail.com (Romain Maneschi) — 2025/11/18

Comment contribuer au développement de GitRoot 11-2025

Alors pourquoi pas de contributeurs externes sur GitRoot ?

Pré-requis

Il n’y a pas grand chose à faire pour être prêt à aider sur GitRoot:

vous devez avoir git
git clone ssh://gitroot.dev
cd gitroot.dev
./gitroot/init.sh

Si vous souhaitez coder il vous faudra en plus:

bash et make (si vous êtes dev il y a de grandes chances que vous les aillez déjà)
installer mise, c’est le plus simple pour avoir tous les compilateurs dans les bonnes versions

Avant de commencer

On peut également en parler par mail contact@gitroot.dev ou sur le fediverse ^{[forge@gitrrot.dev]}(https://gts.gitroot.dev/@forge).

Qu’est-ce qu’on peut faire ?

Corriger les fautes

Moi je veux faire du web

Quand vous êtes content faites une branche avec votre css dans apex, puis git add . et git push je m’occupe du reste.

Moi je veux coder

Bien, pas de soucis, voici une liste de petites tâches (enfin elles me paraissent petites mais si c’est pas le cas pour vous dites le moi):

en golang:
- dans le plugin grafter pouvoir afficher autre chose dans le 1er message d’un graft. La bannière est en dure dans le plugin, il faudrait l’exporter dans la conf du plugin et l’utiliser.
- dans le plugin silo permettre de grouper par fichier ou date
- plus difficile mais j’aimerais bien avoir plus de renderer dans apex, par exemple les infos, warning et autre
en typescript:
- dans le plugin pollen il y a un bug sur le rss il est jamais nettoyé. Rajouté une option (ou pas, 100 en dur me semble être déjà pas mal) pour limiter le nombre d’<item>.
- toujours dans le plugin pollen pourquoi pas rajouter un json feed en plus du rss. On peut serializer du json en assemblescript.
- plus difficile mais il serait bien de pouvoir dire au plugin pollen de générer un rss avec le contenu des fichiers. Ça permettrait à GitRoot d’avoir un rss affichant les articles du blog par exemple. Aujourd’hui il ne met dans le rss que les commits.
en rust:
- faire ce que Ygor à dit dans https://floss.social/@ygor/115474535138702961 je ne suis pas un developpeur rust et transformer des String en &str me parle pas beaucoup mais si vous l’êtes je suis sûr que c’est une petite tâche. Le code se trouve dans le plugin sdk et le plugin hop.
- ajouter un fakeServer au plugin sdk pour faciliter les tests d’un plugin, voici celui de go https://gitroot.dev/worktree/app/libs/golang/plugin/test/fakeserver.go.html

Moi je suis sysadmin

Parfait il y a de quoi faire aussi:

aujourd’hui il y a trop d’étapes pour releaser GitRoot, automatiser au maximum m’aiderais beaucoup.
si vous avez un petit de place sur un de vos serveurs, tester de déployer une instance juste pour le fun. Peu être vous pourrez améliorer la doc ou trouver quelque chose qui ne marche plus. Ou ajouter un paragraphe pour utiliser gitroot avec nginx ou autre.

Moi je veux tester

tous les tests sont en bash dans testsuite/runtest.sh se trouve le plus gros test, à côté il y en d’autres
- exécutez les pour voir s’ils marchent chez vous me parait une bonne première tâche
- en créer de nouveaux
- améliorer les existants en sortant par exemple des fonctions helper comme quiet_git(), report() ou mySleep() dans d’autres fichiers (et les importer) serait d’une grande aide pour le projet. Vous pouvez aussi créer des nouveaux pour killGitroot() qui est fait en début de chaque fichier. Ou createProject() qui consiste à chaque fois à aller dans le root repository et ajouter son nom dans le fichier .gitroot/repositories.yml.

Moi je veux juste réfléchir/discutter

Tu es le bienvenue sur le channel gitroot dans matrix. Ou par mail contact [AT] gitroot.dev ou sur le fediverse @forge@gitroot.dev sur ce serveur.

How to help building GitRoot

rmaneschi@gmail.com (Romain Maneschi) — 2025/11/18

How to help building GitRoot 11-2025

This article is the translation of french version thanks to DeepL

So why not have external contributors on GitRoot?

Prerequisites

There isn’t much you need to do to get ready to help out on GitRoot:

you need to have git
git clone ssh://gitroot.dev
cd gitroot.dev
./gitroot/init.sh

If you want to code, you will also need:

bash and make (if you are a developer, chances are you already have them)
Install mise, which is the easiest way to get all the right versions of the compilers

Before we begin

We can also talk about it by email contact@gitroot.dev or on the fediverse ^{[forge@gitrrot.dev]}(https://gts.gitroot.dev/@forge).

What can we do?

Correct mistakes

I want to work on the web

It would be great to create (or find) a theme. GitRoot currently uses simplecss, and it only needs classless CSS. There are many available, but you can also create one for GitRoot.

When you are satisfied, create a branch with your CSS in apex, then git add . and git push. I’ll take care of the rest.

I want to code

Okay, no worries, here’s a list of small tasks (well, they seem small to me, but if that’s not the case for you, let me know):

in golang:
- in the grafter plugin, be able to display something else in the first message of a graft. The banner is hard-coded in the plugin; it would need to be exported to the plugin configuration and used.
- In the silo plugin, allow grouping by file or date
- More difficult, but I would like to have more renderers in apex, for example info, warnings, and others
in typescript:
- in the pollen plugin there is a bug in the RSS feed it is never cleaned up. Added an option (or not, 100 seems fine to me) to limit the number of <item>.
- Still in the pollen plugin, why not add a json feed in addition to the RSS feed? We can serialize json in assemblescript.
- More difficult, but it would be nice to be able to tell the pollen plugin to generate an RSS feed with the contents of the files. This would allow GitRoot to have an RSS feed displaying blog articles, for example. Currently, it only puts commits in the RSS feed.
in Rust:
- Do what Ygor said in https://floss.social/@ygor/115474535138702961 I’m not a Rust developer and converting String to &str doesn’t mean much to me, but if you are, I’m sure it’s a small task. The code can be found in the plugin sdk and the hop plugin.
- Add a fakeServer to the plugin sdk to facilitate plugin testing. Here is the one for Go https://gitroot.dev/worktree/app/libs/golang/plugin/test/fakeserver.go.html

I’m a sysadmin.

Perfect, there’s plenty to do:

Today, there are too many steps to release GitRoot. Automating as much as possible would help me a lot.
If you have a little space on one of your servers, try deploying an instance just for fun. Maybe you can improve the documentation or find something that no longer works. Or add a paragraph on using gitroot with nginx or something else.

I want to test

All tests are in bash in /app/testsuite/. The largest test is located in runtest.sh, along with others.
- Running them to see if they work on your system seems like a good first task to me.
- Creating new ones
- Improving existing ones by, for example, moving helper functions such as quiet_git(), report(), or mySleep() to other files (and importing them) would be a great help to the project. You can also create new ones for killGitroot(), which is done at the beginning of each file. Or createProject(), which consists of going to the root repository each time and adding its name to the .gitroot/repositories.yml file

I just want to think/discuss

You are welcome to join the gitroot channel on Matrix. Or contact us by email at contact [AT] gitroot.dev or on the Fediverse at @forge@gitroot.dev on this server.

Issues, Tickets, Discussions... Call them what you want!

rmaneschi@gmail.com (Romain Maneschi) — 2026/06/08

Issues, Tickets, Discussions… Call them what you want!

Many of you, when checking out https://gitroot.dev, have told me that the 🐞 Issues button shouldn’t be labeled “Issues”, but rather “Tickets” or “Discussions”.

The Original Idea

In traditional forges, an “issue” consists of a title and a description created by a user. We can represent it like this:

Easy, right? Well, how do you represent that in GitRoot using only files? This question was running through my mind for months before I finally found a solution.

The Basic Solution

A simple text format that handles metadata perfectly is Markdown. I use Markdown here, but any other markup language could work. Let’s create a file named issues/1.md:

1---
2id: 1
3user: email@email.com
4status: OPEN
5---
6
7# My title
8
9My description where I can detail what my problem is.

Yes, it really is that simple. In GitRoot, to create an issue, you just create a file, add some metadata, commit, and push. Boom, you have an issue.

A Better Solution

1# My title
2
3My description where I can detail what my problem is.

Then, we run git commit && git push. Since I have configured the ladybug plugin like this:

 1- name: ladybug
 2  ...
 3  - path: issues/**/*.md
 4    branch:
 5    - "*"
 6    when:
 7    - add
 8    - mod
 9    func: []
10    write:
11      git:
12      - path: issues/**/*.md
13        can:
14        - mod
15      web: []
16      exec: []
17      callfunc: []
18    configuration:
19      metadata:
20      - default: autogenerated
21        mandatory: true
22        name: id
23        type: crc16
24      - default: OPEN
25        mandatory: true
26        name: status
27        type: string
28      - default: email@email.com
29        mandatory: false
30        name: user
31        type: string

You can read this configuration as: “For every Markdown file in the issues directory across all branches, if the file doesn’t have these metadata fields, automatically add these default values.”

Now, if you are a Git purist, a server creating commits right on top of yours might sound a bit radical, or even terrifying. But look closely at the write block in the YAML configuration above:

1write:
2  git:
3    - path: issues/**/*.md
4      can:
5        - mod

So, once you push, the server-side plugin does its job, and the next time you run git pull, your local file will automatically look like this:

1---
2id: 1
3user: email@email.com
4status: OPEN
5---
6
7# My title
8
9My description where I can detail what my problem is.

So, What About the Label?

First, we need a file that lists all of these “issues”. That’s exactly why the silo plugin exists. It inspects all files and groups them whenever it finds a matching pattern.

To list all open “issues”, we configure it like this:

 1- name: silo
 2  ...
 3  run:
 4  - path: "**/*"
 5    branch:
 6    - main
 7    when:
 8    - add
 9    - mod
10    - del
11    func: []
12    write:
13      git:
14      - path: boards/*.md
15        can:
16        - add
17        - mod
18        - del
19        - append
20      web: []
21      exec: []
22      callfunc: []
23    configuration:
24      boards:
25        description: All open issues
26        for: issues/*.md
27        format: table
28        paginator: 50
29        selects:
30        - "status: (.*)"
31        - "user: (.*)"
32        sort: select[0]
33        sortOrder: desc
34        tableHeader: "| | status | user |"
35        title: All issues
36        to: boards/issues.md
37        where: "status: OPEN"

You can read this configuration as: “For every file in the main branch, create a board called ‘All issues’ containing links to all files matching status: OPEN. Display them as a table with status and user columns.”

After running git commit && git push && git pull, you will get a new file at boards/issues.md containing something like this:

1# All issues
2
3All open issues
4
5|                                   | status | user            |
6| --------------------------------- | ------ | --------------- |
7| [My title](../issues/my_issue.md) | OPEN   | email@email.com |

Now that we have a page representing all our issues, we can finally render it in the browser. Because, as you might have guessed, the label causing all this debate lives in the Web UI.

The Web is Where It Happens

To render my boards/issues.md file on the web, I use the apex plugin, in conjunction with the apex_markdown plugin, of course.

These plugins take files from git and render them directly in the Web UI. I configure them like this:

 1- name: apex
 2  ...
 3  run:
 4  - path: "**/*"
 5    branch:
 6    - main
 7    when:
 8    - add
 9    - mod
10    - del
11    func: []
12    write:
13      git:
14      - path: "**/*"
15        can:
16        - add
17        - mod
18        - del
19        - append
20      web:
21      - path: "**/*"
22        can:
23        - add
24        - mod
25        - del
26        - append
27      exec: []
28      callfunc:
29      - pluginname: apex_markdown
30        funcname: renderMd
31      ...
32    configuration:
33      ...
34      menu:
35      - display: 🏠 Home
36        link: /
37      - display: 📖 Documentation
38        link: /doc/
39      - display: 🔖 Versions
40        link: /CHANGELOG.html
41      - display: �� Plugins
42        link: /plugins/
43      - display: �� Issues
44        link: /boards/issues.html
45      - display: 🚀 Code
46        link: /worktree/
47      - display: ☕ Blog
48        link: /blog/
49      - display: �� Contact
50        link: /contact.html

If you are wondering how Apex magically knows where to find your “issues”, the secret is: it doesn’t.

Conclusion

I’m pretty sure you now understand why I didn’t immediately jump on resolving this task: everything we just saw is pure configuration, completely separated from the GitRoot core code.

In fact, I personally call them TODOs, because in reality, they are all just waiting for me to get them done.

Wait… Why stop at issues?

This is where the true power of GitRoot will blow your mind.

Yes, you read that right. You can visit it live at https://gitroot.dev/boards/todos.html.

If you want to discover more plugins and configurations, feel free to browse through the 🧩 Plugins section. However, for now, the best way to explore remains checking out the actual GitRoot plugins.yml configuration file.

Blog of gitroot.dev

0.5.0 plugins

What is GitRoot without its plugins?

All plugins are compatible with the 0.5.0

Firefly in zig

Silo, lots of new things

Apex is the web view

Grafter diff

Pollen render content

What next?

0.5.0

Move slowly, and take care of things

If you only have 5 minutes

Breaking PURL

A lot of people have discovered GitRoot

Not conclusive

Before it’s too late

My new favorite language…. until the next one

Plugins needs more power

Sftp to save the web

How many bugs?

In-depth Details

PURL breaking details

GitRoot communication

SdkGenerator full story

Max anonymous branches

Zig plugin-sdk

PluginSdk improvements

Sftp feature

Some interesting bug fixes

What next?

0.4.0

The teenager starts building its own future

If you only have 5 minutes

The thing i’m most proud of

The thing with the most visibility

The thing that changes everything but was so simple

The thing that was more complex than I thought

The things I’m just happy are done

In-depth Details

Executor

Plugin registry

Apex render branch

Plugin deps

Sigma plugin

FS plugin-sdk

What next?

0.3.0

From “baby to teenager” GitRoot become a forge

If you only have 5 minutes

In-depth Details

For admin: activating an executor

Bare Metal: simplest but most dangerous

Bubblewrap (bwrap): lightweight sandboxing

Container: heavyweight but most flexible

SSH: remote execution (alpha)

For user: using the hop plugin

Plugin api report and reporter

GitRoot bets on mise

Communication and community building

Apex a better web experience

And others useful updates

ForgeConf update

Integrated updater

Rust and WASM

0.2.0

Version 0.2.0 is here

First contribution

No notification == no contribution

Lot of bugs

Let’s the show continue

No linux == no gitroot

Doc, doc… doc?

A lot more

More technicals bugs

Simplify plugin install

What next?

0.1.0

GitRoot 0.1.0 is deployed 🎉��

GitRoot in numbers:

For user: using the `hop` plugin