Contributing

First off, thank you for considering contributing to Burrito! Your support helps make this project better for everyone.

The following is a set of tutorials and guidelines for contributing to Burrito. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document.

How Can I Contribute?

Reporting Bugs

If you find a bug, please report it by opening an issue on the issue tracker. Before reporting, please check whether the issue has already been reported.

Ensure the bug hasn't been reported yet.
Use a clear and descriptive title.
Provide detailed steps to reproduce the issue.
Include any relevant logs or screenshots.

Suggesting Enhancements

We welcome suggestions for improvements. Please use the issue tracker to submit enhancement requests.

Use a clear and descriptive title.
Explain why this enhancement would be useful.
Provide examples or mockups if possible.

Contributing Code

Set up a development environment following the steps below.
Read the Development Guidelines.
Submit contributions!

Getting Started: Set Up a Local Development Environment (kind)

Prerequisites

Go 1.26+ (matches go.mod/CI) — required for make build, make test, make vet, golangci-lint, and go install of tools such as dlv
Docker with Buildx and Compose — the make upgrade-*-kind and make test targets are docker-specific (docker buildx build --load, kind load docker-image, docker compose)
Git
Kind
Helm
kubectl
yq
make
golangci-lint (optional, recommended) — has no make target; run golangci-lint run ./... before pushing (CI enforces it)

controller-gen, kustomize, and setup-envtest are installed automatically into ./bin by the relevant make targets — no manual install needed.

For UI development you also need Node.js 24 and Yarn (classic) — see ui/AGENTS.md for the UI workflow.

Using mise (recommended)

This repository ships a mise.toml that pins the exact versions of the tools above with mise, so every contributor gets an identical environment. After installing mise, run from the repository root:

mise install        # install all pinned tools (Go, Node, Yarn, kubectl, helm, kind, yq, golangci-lint, uv)

Docker (with Buildx and Compose), make and Git are system-level tools and are not managed by mise — install them yourself.

mise.toml also defines a few tasks:

mise run lint          # golangci-lint run ./...
mise run mkdocs-serve  # live docs preview (see "Building the Documentation Locally")

To run an instance of Burrito, you will need a Kubernetes cluster. This tutorial uses Kind as a local development Kubernetes cluster.

Follow Kind's quick start tutorial to set up a local cluster.

Once your cluster is up and running, follow the next steps to compile and deploy Burrito.

Basic Install

Follow these steps to install a minimal working configuration of Burrito on a Kind cluster:

Cert-manager
Burrito controllers in the burrito-system namespace
A datastore running with mock storage (in-memory)
A TerraformRepository and an associated TerraformLayer resource in the burrito-project namespace, pointing to the padok-team/burrito-examples repository

Before starting, check that your local Kind cluster is running and that your context is set to target this cluster.

Install cert-manager on your cluster:

helm install cert-manager oci://quay.io/jetstack/charts/cert-manager \
    --version v1.20.2 \
    --namespace cert-manager \
    --create-namespace \
    --set crds.enabled=true

Fork and clone this repository.
Run the following command to build a local image of Burrito, load it into your Kind cluster, and install Burrito with development Helm values:
```
make upgrade-dev-kind
```

Check that Burrito is running in the burrito-system namespace:

kubectl get pods -n burrito-system

The output should be similar to:

NAME                                  READY   STATUS    RESTARTS   AGE
burrito-controllers-7657b7455-2ldtd   1/1     Running   0          5m32s
burrito-datastore-5967f46497-tfzgg    1/1     Running   0          5m32s
burrito-server-5b6fb78949-ngcnt       1/1     Running   0          5m32s

Create layers and repository resources:

Create a dev directory in deploy/charts/burrito/templates/ and add a dev.yaml manifest with development resources:

apiVersion: config.terraform.padok.cloud/v1alpha1
kind: TerraformLayer
metadata:
    name: my-layer
    namespace: burrito-project
spec:
    branch: main
    path: terraform/
    repository:
        name: my-repository
        namespace: burrito-project
---
apiVersion: config.terraform.padok.cloud/v1alpha1
kind: TerraformRepository
metadata:
    name: my-repository
    namespace: burrito-project
spec:
    repository:
        url: https://github.com/padok-team/burrito-examples
    remediationStrategy:
        autoApply: true
    terraform:
        enabled: true
    opentofu:
        enabled: false
    terragrunt:
        enabled: false

Refresh your Helm configuration:
```
make upgrade-dev-helm
```

Check that a runner pod is created for the newly created layer:

kubectl get pods -n burrito-project

The output should be similar to:

NAME                   READY   STATUS      RESTARTS   AGE
my-layer-apply-gxjhd   0/1     Completed   0          2m36s

Refresh Commands

To build a new local image of Burrito, push it into your local Kind cluster, and update the Helm release with the new image tag, run the following:

make upgrade-dev-kind

To refresh the Helm chart with development values, run:

make upgrade-dev-helm

Check the Makefile for more details about these commands.

Advanced Settings

Configure a GitHub Token for TENV:

It is strongly recommended to create a GitHub token with no specific rights to bypass the GitHub API rate limiting. Append the following configuration to your development TerraformRepository resources:

  overrideRunnerSpec:
    env:
      - name: TENV_GITHUB_TOKEN
        value: ghp_xxxxx

Development Guidelines

Testing

Write tests for new features or bug fixes.
Run all tests to ensure existing functionality isn't broken (make test).
Ensure code coverage remains at the same level or higher.

Commit Messages

Please follow the convention described by Conventional Commits.
If you don't, the CI pipeline will fail.

Building the Documentation Locally

The documentation site is built with MkDocs.

If you use mise, the toolchain (uv) is already available and a task is provided:

mise run mkdocs-serve   # installs deps into .venv, then serves at http://127.0.0.1:8000

Otherwise, with Python 3 directly:

pip install -r requirements.txt   # mkdocs + material theme + plugins
mkdocs serve                      # live preview at http://127.0.0.1:8000
mkdocs build --strict             # what CI runs; fails on broken links

CI also lints Markdown with markdownlint-cli2 using docs/.markdownlint.jsonc.

Additional Resources

Controller-runtime documentation (Burrito heavily relies on this package)
Burrito documentation

Debugging Burrito

To debug Burrito efficiently in Kubernetes, you can use Delve, optionally with Visual Studio Code (recommended). We have set a few things to help you getting started.

You'll need to follow instructions in Getting Started: Set Up a Local Development Environment (kind) to get a local Kubernetes development instance.

Enable debugging

First, being by installing dlv: go install github.com/go-delve/delve/cmd/dlv@latest

We'll rely on deploy/charts/burrito/values-debug.yaml to deploy the configuration to start the debugging session.

By default, the different component debug configs are commented in the Helm values. Indeed, starting the application with dlv server will hang until you connect with the dlv client so it has to be enabled only when you need it.

# config:
#   burrito:
#     runner:
#       command: ["/usr/local/bin/dlv"]
#       args: ["--listen=0.0.0.0:2346", "--headless=true", "--accept-multiclient", "--api-version=2", "--log", "exec", "/usr/local/bin/burrito", "runner", "start"]

# controllers:
#   deployment:
#     mode: Debug
#     command: ["/usr/local/bin/dlv"]
#     args: ["--listen=0.0.0.0:2345", "--headless=true", "--accept-multiclient", "--api-version=2", "--log", "exec", "/usr/local/bin/burrito", "controllers", "start"]

# datastore:
#   deployment:
#     mode: Debug
#     command: ["/usr/local/bin/dlv"]
#     args: ["--listen=0.0.0.0:2347", "--headless=true", "--accept-multiclient", "--api-version=2", "--log", "exec", "/usr/local/bin/burrito", "datastore", "start"]

# server:
#   deployment:
#     mode: Debug
#     command: ["/usr/local/bin/dlv"]
#     args: ["--listen=0.0.0.0:2348", "--headless=true", "--accept-multiclient", "--api-version=2", "--log", "exec", "/usr/local/bin/burrito", "server", "start"]

!!! note The runner command+args override isn't under runner.deployment as other components as it's not a k8s deployment

!!! tip You can also launch burrito with the debug build and override command+args in overrideRunnerSpec in a specific layer you'd like to debug.

By default, we'll start the application with the usual command. If you want to debug the controller or the runner, uncomment the required block. This will open a port on the pod on which you'll connect from your computer.

mode: Debug is removing liveness and readiness probes: they won't be able to start as dlv will await for you to start the debugging session.

Deploy/refresh commands

You'll need to deploy the debug container images and config. This is the same command if you need to refresh your deployment.

To build a new local debug image of Burrito, push it into your local Kind cluster, and update the Helm release with the new image tag, run the following:

make upgrade-debug-kind

To refresh the Helm chart with debug values, run:

make upgrade-debug-helm

Check the Makefile for more details about these commands.

Connect from your computer to the debug session

The debugging port won't be exposed by default so you'll need to port-forward it.

For the controller:

kubectl port-forward $(kubectl get pods -n burrito-system | awk '/burrito-controllers.*Running/{print $1}') -n burrito-system 2345:2345

For the runner:

kubectl port-forward -n burrito-project <layerName> 2346:2346

It will listen on the same port than the controller so we're exposing it on port 2346 on your computer so you can debug the controller and the runner if needed.

For the datastore:

kubectl port-forward $(kubectl get pods -n burrito-system | awk '/burrito-datastore.*Running/{print $1}') -n burrito-system 2347:2347

For the server:

kubectl port-forward $(kubectl get pods -n burrito-system | awk '/burrito-server.*Running/{print $1}') -n burrito-system 2348:2348

Start debugging

With vscode

!!! note You can get more information about Vscode+Go debugging here

If you want to use Vscode to debug the app, you'll need to get the Go extension and create a .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Controller",
            "type": "go",
            "request": "attach",
            "mode": "remote",
            "port": 2345,
            "host": "127.0.0.1",
            "apiVersion": 2
        },
        {
            "name": "Attach to Runner",
            "type": "go",
            "request": "attach",
            "mode": "remote",
            "port": 2346,
            "host": "127.0.0.1",
            "apiVersion": 2
        },
        {
            "name": "Attach to Datastore",
            "type": "go",
            "request": "attach",
            "mode": "remote",
            "port": 2347,
            "host": "127.0.0.1",
            "apiVersion": 2
        },
        {
            "name": "Attach to Server",
            "type": "go",
            "request": "attach",
            "mode": "remote",
            "port": 2348,
            "host": "127.0.0.1",
            "apiVersion": 2
        }
    ]
}

!!! question "New to debugging on Vscode?" For a vscode debug introduction, you can check Debug code with Visual Studio Code.

Browse your code to set breakpoints by clicking on the left side of your line.

Open the Run and Debug pane, select your debugging configuration and hit F5 to connect to the remove dlv.

Once your line is reached, vscode will show you the variables, current stack, etc

With `dlv`

If you prefer to debug on cli, you can connect with dlv connect 127.0.0.1:<debuggingPort> where <debuggingPort> is 2345, 2346, 2347 or 2348, depending on what you're debugging.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Contributing

How Can I Contribute?

Reporting Bugs

Suggesting Enhancements

Contributing Code

Getting Started: Set Up a Local Development Environment (kind)

Prerequisites

Using mise (recommended)

Basic Install

Refresh Commands

Advanced Settings

Development Guidelines

Testing

Commit Messages

Building the Documentation Locally

Additional Resources

Debugging Burrito

Enable debugging

Deploy/refresh commands

Connect from your computer to the debug session

Start debugging

With vscode

With `dlv`

Uh oh!

FilesExpand file tree

index.md

Latest commit

History

index.md

File metadata and controls

Contributing

How Can I Contribute?

Reporting Bugs

Suggesting Enhancements

Contributing Code

Getting Started: Set Up a Local Development Environment (kind)

Prerequisites

Using mise (recommended)

Basic Install

Refresh Commands

Advanced Settings

Development Guidelines

Testing

Commit Messages

Building the Documentation Locally

Additional Resources

Debugging Burrito

Enable debugging

Deploy/refresh commands

Connect from your computer to the debug session

Start debugging

With vscode

With dlv

With `dlv`