GitLab Terraform Provider: Kroki Support in Application Settings

Context

GitLab supports Kroki at the instance settings level, allowing server-side diagram rendering for formats such as BPMN, Mermaid, BlockDiag, and Excalidraw.

In Terraform, instance-wide GitLab settings are managed through the gitlab_application_settings resource. This resource exposes GitLab’s Settings API through Infrastructure-as-Code so administrators can declaratively manage platform behavior.

Problem

The GitLab Terraform Provider did not expose Kroki-related configuration fields in gitlab_application_settings, even though the GitLab API already supported them.

This meant administrators managing GitLab through Terraform could not configure Kroki declaratively and instead had to rely on manual API calls or the GitLab UI.

The missing settings were:

• kroki_enabled
• kroki_url
• kroki_formats

My Contribution

I added Kroki support to the gitlab_application_settings Terraform resource by implementing schema support, API update handling, state mapping, and documentation examples.

• Added Terraform schema attributes for kroki_enabled, kroki_url, and kroki_formats
• Implemented provider logic to map Terraform configuration into the GitLab settings update request
• Added read/state handling so Kroki values returned by the API are correctly reflected in Terraform state
• Fixed a state drift issue caused by default Kroki format values returning as explicit false values
• Marked kroki_formats as computed to prevent perpetual diffs
• Added provider docs and example configuration

Kroki Sketches

While working on this contribution, I made a couple of sketches of Kroki — one happy, and one riding the merge train 🚂🐊

Implementation Details

The final implementation models Kroki support as part of the existing application settings resource, using a Terraform map for format support values.

resource "gitlab_application_settings" "kroki" {
  kroki_enabled = true
  kroki_url     = "https://kroki.io"

  kroki_formats = {
    bpmn       = true
    mermaid    = true
    blockdiag  = false
    excalidraw = false
  }
}

State Drift Fix

GitLab returns Kroki format support as explicit boolean values, including defaults. Without handling, Terraform would detect drift.

This was fixed by normalizing state and marking fields as computed.

Provider Logic

// Simplified provider handling
if d.Get("kroki_enabled").(bool) {
    raw := d.Get("kroki_formats").(map[string]interface{})
    formats := map[string]bool{
        "blockdiag":  false,
        "bpmn":       false,
        "excalidraw": false,
        "mermaid":    false,
    }
    for k, v := range raw {
        if b, ok := v.(bool); ok {
            formats[k] = b
        }
    }
    options.KrokiFormats = &formats
}

Merge Moment

After multiple iterations, reviews, and CI fixes, the merge request successfully made it onto the merge train and was merged into main.

Reward

As a small but meaningful recognition for this contribution, I received a GitLab Lego set. It represents not just the feature itself, but the journey through reviews, CI iterations, and finally reaching the merge train.

I like to think of it as a physical reminder that even small contributions can make a real impact — and that persistence through the process matters.

Final Status

This contribution was successfully merged into the GitLab Terraform Provider main branch on April 4, 2026.

Reflection

This contribution followed the full lifecycle of a Terraform provider feature:

• API capability discovery
• Terraform schema design
• provider update logic implementation
• state mapping and drift prevention
• documentation and example updates
• CI debugging and maintainer review preparation

Although the feature itself is relatively small, it adds practical value for teams managing GitLab instances through Infrastructure-as-Code.

It also reinforced an important lesson in Terraform provider development: schema shape and state behavior matter just as much as the API call itself. A feature is only truly complete when it remains stable across apply, read, and plan.