GitRoot

 1<!--
 2SPDX-FileCopyrightText: 2026 Romain Maneschi <romain@gitroot.dev>
 3
 4SPDX-License-Identifier: CC-BY-SA-4.0
 5-->
 6
 7# Executors
 8
 9An executor allows commands to be run outside of GitRoot. While the plugin system works via WASM, WASM currently doesn't allow us to run all the code, binaries, or tools needed to build a project. For example, running tests or a compiler is not an easy task in WASM. However, doing so on bare metal or in a container (Podman or Docker) is very easy, in fact, almost all CI/CD platforms rely on them.
10
11GitRoot implements this kind of execution through plugins. In this documentation, I will explain how to run commands and how to configure the executor for your forge.
12
13## Using an Executor
14
15Currently, the only plugin that allows the use of an executor is [hop](../../plugins/name/hop.md). Please follow its specific documentation to learn how to run commands.
16
17### Usage
18
19When called by a plugin, an executor handles many tasks. It "automagically" manages cache, environment variables, artifacts, and even statistics. These features are managed by the plugin, and it is up to the plugin to determine which ones are available to you.
20
21## Configuring an Executor
22
23Configuration is handled in the [forgeConfig of the root repository](../technicals/root_repository.md#forgeconfigyml). By setting `enabled: true`, the corresponding executor will be used by your forge. If you activate multiple executors, the first one will be used.
24
25> **Note:** Be careful if you do this. In the future, it will likely be possible to activate multiple executors, allowing plugins to choose exactly where they want to run a command.
26
27## Available Executors
28
29### bareMetal Executor
30
31This is the simplest executor to understand. It runs commands directly on the host. For example, if the `cat` binary is in your path and a user wants to run `cat README.md` in their repository, the bareMetal executor will execute that call.
32
33> **Warning:** This executor should not be activated on shared instances where users cannot be fully trusted.
34
35### Bwrap Executor
36
37This executor uses [bubblewrap](https://github.com/containers/bubblewrap), which is a _"low-level unprivileged sandboxing tool used by Flatpak and similar projects"_.
38
39This executor is ideal for `mono-project` instances where all build and test requirements are known. For instance, on [gitroot.dev](https://gitroot.dev), we use it with [mise](https://mise.jdx.dev/) to install, update, and cache binaries on the host. We want to ensure that users don't break the build without allowing arbitrary tools.
40
41### Container Executor
42
43This is likely the executor you are looking for. It runs Podman (or Docker) images on the host, allowing users to perform any actions they need within the container.
44
45Unlike other forges, GitRoot allows you to pass a `Containerfile` (or `Dockerfile`). In this case, GitRoot builds the image before running the command.
46
47### SSH Executor
48
49If the host machine is not sufficient, the SSH executor allows you to run commands on a remote machine.
50
51> **Warning:** We do not recommend using this executor for now, as it requires further development.