An 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.
GitRoot 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.
Currently, the only plugin that allows the use of an executor is hop. Please follow its specific documentation to learn how to run commands.
When 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.
Configuration is handled in the forgeConfig of the root repository. By setting enabled: true, the corresponding executor will be used by your forge. If you activate multiple executors, the first one will be used.
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.
This 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.
Warning: This executor should not be activated on shared instances where users cannot be fully trusted.
This executor uses bubblewrap, which is a “low-level unprivileged sandboxing tool used by Flatpak and similar projects”.
This executor is ideal for mono-project instances where all build and test requirements are known. For instance, on gitroot.dev, we use it with mise to install, update, and cache binaries on the host. We want to ensure that users don’t break the build without allowing arbitrary tools.
This 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.
Unlike other forges, GitRoot allows you to pass a Containerfile (or Dockerfile). In this case, GitRoot builds the image before running the command.
If the host machine is not sufficient, the SSH executor allows you to run commands on a remote machine.
Warning: We do not recommend using this executor for now, as it requires further development.