GitLab

The GitLab plugin lets formae manage project-scoped CI/CD resources: variables, environments, repository files, and typed .gitlab-ci.yml pipelines.

Repository: formae-plugin-gitlab

Installation

git clone https://github.com/platform-engineering-labs/formae-plugin-gitlab.git
cd formae-plugin-gitlab
make install

This builds the plugin and installs it to ~/.pel/formae/plugins/gitlab/. The formae agent discovers installed plugins automatically on startup. Requires Go 1.26+.

Configuration

Target

Point a target at a GitLab group and project:

import "@formae/formae.pkl"
import "@gitlab/gitlab.pkl"

target: formae.Target = new formae.Target {
    label = "gitlab"
    namespace = "GitLab"
    config = new gitlab.Config {
        group = "my-group"
        project = "my-project"
    }
}

Both group and project are required. All resources in this target are scoped to group/project.

Credentials

The plugin resolves a GitLab personal access token in this order:

1. GITLAB_TOKEN environment variable
2. glab auth status from the glab CLI
3. ~/.config/glab-cli/config.yml (or ~/Library/Application Support/glab-cli/config.yml on macOS)

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

The token needs the api scope. Tokens are never stored in the target config.

Typed pipelines

GitLab::Project::Pipeline writes .gitlab-ci.yml (or any path you pick) as a GitLab::Project::File under the hood. Author stages, jobs, rules, and workflow in Pkl and let the plugin render the YAML. That gets you type checking, imports, and shared snippets across projects without hand-editing YAML.

Examples

The infra-to-app example provisions an Azure PostgreSQL database, deploys a Miniflux container, and verifies the app from a single pipeline. The GitLab plugin manages the pipeline and masked CI/CD variables; the Azure plugin handles the infrastructure.

Clone the repo and resolve Pkl dependencies before running:

git clone https://github.com/platform-engineering-labs/formae-plugin-gitlab.git
cd formae-plugin-gitlab
pkl project resolve examples/infra-to-app

# Apply the resources (requires GITLAB_TOKEN and the Azure env vars
# documented in the example README)
formae apply --mode reconcile --yes examples/infra-to-app/main.pkl

Supported Resources

Type	Description	Native ID	Discoverable	Extractable
GitLab::Project::Variable	CI/CD variables (supports masked and protected)	key	Yes	Yes
GitLab::Project::Environment	Deployment environments with tier and external URL	name	Yes	Yes
GitLab::Project::File	Repository files on a given branch	path	Yes	Yes
GitLab::Project::Pipeline	Typed .gitlab-ci.yml with stages, jobs, and workflow rules	path	Yes	Yes

All four types are project-scoped. Group-level resources are not implemented.

What's next

• Write pipelines in Pkl with the typed ci/pipeline.pkl job model
• See Target for how targets scope resources
• Pair with the Azure plugin for end-to-end infra-to-app flows

Release notes

See release notes for changes per version.