GitLab Terraform Provider: Kroki Support in Application Settings

Context

The GitLab instance-level Settings API supports configuring integrations such as Kroki, which enables server-side diagram rendering for formats like BPMN, BlockDiag, and Excalidraw.

In Terraform, instance configuration is managed through the gitlab_application_settings resource. This resource exposes GitLab’s Settings API through Infrastructure-as-Code, allowing administrators to declaratively manage instance behavior.

Problem

The GitLab Terraform Provider did not expose Kroki configuration fields even though they were already supported by the GitLab API.

This meant administrators managing GitLab instances via Terraform could not configure Kroki declaratively and had to fall back to manual API calls or UI configuration.

The missing API fields were:

• kroki_enabled
• kroki_url
• kroki_formats

My Contribution

I implemented Kroki support within the gitlab_application_settings Terraform resource by adding schema attributes, state handling, and update logic.

• Added Terraform schema attributes: kroki_enabled, kroki_url, and kroki_formats
• Implemented update logic to translate Terraform configuration into the GitLab API request struct
• Mapped API responses back into Terraform state so plans remain stable and idempotent
• Added acceptance test coverage validating both enabling and disabling Kroki through Terraform
• Refactored the schema design during code review from a raw map to a typed nested block to improve validation and user experience
• Added example configuration to the provider documentation examples directory

Terraform Schema Design

The Kroki integration is represented in Terraform in a way that matches the structure of the GitLab API while also following Terraform provider design conventions.

After review feedback, the format configuration was implemented as a typed nested block instead of a free-form map. This ensures unsupported keys cannot be passed to the API.

resource "gitlab_application_settings" "kroki" {

  kroki_enabled = true
  kroki_url     = "https://kroki.io"

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

}

The schema also enforces dependency constraints between kroki_enabled and kroki_url so invalid configurations fail during Terraform planning rather than during API execution.

Provider Implementation

Within the provider implementation, the Terraform configuration must be translated into the Go client used by the GitLab API.

The nested Kroki block is extracted from Terraform state and converted into a map[string]bool which matches the GitLab API client structure.

// Update handling inside gitlabApplicationSettingsToUpdateOptions

if d.HasChange("kroki_formats") {

    raw := d.Get("kroki_formats").([]interface{})

    if len(raw) > 0 {

        cfg := raw[0].(map[string]interface{})

        formats := map[string]bool{
            "bpmn":       cfg["bpmn"].(bool),
            "blockdiag":  cfg["blockdiag"].(bool),
            "excalidraw": cfg["excalidraw"].(bool),
        }

        options.KrokiFormats = &formats
    }
}

The provider also includes corresponding logic to map API responses back into Terraform state so that subsequent terraform plan operations remain stable.

Acceptance Testing

The provider uses acceptance tests to validate real API behavior against a GitLab instance.

The Kroki tests verify that Terraform can both enable and disable the integration correctly.

// Acceptance test workflow (simplified)

Step 1:
Enable Kroki
  kroki_enabled = true
  kroki_url     = "https://kroki.io"

Step 2:
Disable Kroki
  kroki_enabled = false

The test validates that the provider correctly updates
GitLab application settings without causing drift.

Merge Request Evolution

The initial implementation was submitted as MR !2953.

During maintainer review, several improvements were requested, including:

• Refactoring the schema for better validation
• Resolving merge conflicts with upstream changes
• Improving the provider update logic
• Formatting improvements in acceptance tests

To address these changes cleanly, the branch was recreated and the updated implementation was submitted as MR !3005.

Current Status

The updated implementation is currently under review in Merge Request !3005.

Once merged, GitLab administrators will be able to configure Kroki integration entirely through Terraform.

Reflection

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

• API capability discovery
• Terraform schema design
• provider update logic implementation
• state mapping
• acceptance testing
• maintainer review and iteration

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

This contribution also reinforced an important lesson in Terraform provider development: well-designed schemas are critical. Once the provider correctly models the API contract, Terraform becomes a reliable interface for managing complex platform configuration.