feat(gitlab): add GitLab platform example with Replicated SDK and CMX validation

[kriscoleman]

I paired on this with @mikhailswift

Summary

• Adds a GitLab 18.x platform example using the gitlab/gitlab Helm chart (v9.0.2) wrapped as a Helm dependency
• Integrates the Replicated SDK subchart for license validation and instance telemetry
• Includes KOTS manifests: preflight checks, support bundle spec, config screen, HelmChart CR, and Embedded Cluster extensions
• Adds a GitHub Actions CI/CD workflow for lint, Helm template validation, release creation, and stable channel promotion
• Validates deployment via Replicated Compatibility Matrix (CMX) on k3s 1.32

Key design decisions

• Wrapper chart pattern: Thin wrapper (applications/gitlab/charts/gitlab/) that depends on upstream gitlab/gitlab rather than vendoring it, keeping the chart maintainable
• External PostgreSQL and Redis: Bundled Bitnami images were removed from Docker Hub; the example deploys postgres:16 and redis:7 as external StatefulSet/Deployment services
• SDK opt-in via condition: replicated.enabled condition allows disabling the SDK for raw Helm CMX validation (no license required)

Test plan

• helm dependency update in applications/gitlab/charts/gitlab/ succeeds
• helm template with tests/helm/ci-values.yaml renders without errors
• GitLab pods reach Running state on a k3s 1.32 cluster via CMX
• Preflight checks pass (k8s >= 1.26, CPU >= 4 cores, RAM >= 12Gi)
• Support bundle collectors capture webservice, sidekiq, kas, gitaly logs

🤖 Generated with Claude Code

[kriscoleman]

[kriscoleman]

GasTown prompt used to build this with a couple feedback loops, this helped me iterate both on the agent instructions and the GitLab platform example:

Mayor Mission: Automate Replicated Onboarding for GitLab Helm Charts

Objective

We are building a new platform example for GitLab (https://docs.gitlab.com/charts/) in the repl_examples rig, proving that our Replicated onboarding agent instructions (installed globally in claude) can automate onboarding a complex Helm-based platform onto the Replicated platform. The end state is two deliverables:

1. A working GitLab platform example in repl_examples — with Replicated CI/CD GitHub workflows, Replicated SDK integration, and the application running successfully in CMX (Compatibility Matrix).
2. A refined, battle-tested claude plugin for Replicated onboarding in repl_claude_mktplc on branch add-replicated-onboarding-plugin — with all gaps discovered during the GitLab onboarding fixed, passing ailloy lint and ailloy assay with zero errors, warnings, or hints.

Environment

• Replicated CLI auth: The environment variable $REPL_GITLAB_SA_TOKEN is set on my machine and available to all agent sessions. Use this as the service account token for any replicated CLI commands.
• Rigs:
  • repl_examples — the platform_examples repo (https://github.com/replicatedhq/platform_examples). This is where the GitLab example gets built.
  • repl_claude_mktplc — the Replicated Claude marketplace repo, currently on branch add-replicated-onboarding-plugin. This contains the onboarding agent instructions we're dogfooding.

Phase 1: Implement GitLab Platform Example via Onboarding Agents

Work in the repl_examples rig.

Step 1: Understand the existing patterns

• Review the existing platform examples in repl_examples to understand the structure, conventions, and patterns used (directory layout, CI/CD workflows, Replicated SDK integration patterns, CMX configuration).
• Review GitLab's Helm chart documentation at https://docs.gitlab.com/charts/ to understand the chart structure, subcharts, values, and deployment requirements.

Step 2: Use the onboarding agents to onboard GitLab

• The Replicated onboarding agent instructions are already installed globally. Use them to onboard GitLab's Helm charts onto the Replicated platform.
• The onboarding agents follow a Coding → Review feedback loop: the Coding agent implements the Replicated patterns (SDK integration, preflight checks, support bundle specs, CI/CD workflows, CMX compatibility matrix), then the Review agent validates that the application is correctly configured and running in CMX.
• This feedback loop should work naturally — the Coding agent implements, the Review agent validates, and if validation fails, the Coding agent iterates. If this control loop does NOT work naturally (e.g., the agents don't hand off correctly, the Review agent can't validate, the Coding agent doesn't know how to fix validation failures), that is a gap in the agent instructions that needs to be reported and fixed in Phase 2.
• Keep detailed notes on any friction, gaps, unclear instructions, missing context, or failures encountered during onboarding. These are the inputs for Phase 2.

Step 3: Validate success

• The GitLab application must be running successfully in CMX.
• The platform example must include: Replicated CI/CD GitHub workflows (using replicatedhq/replicated-actions), Replicated SDK integration, preflight checks, support bundle specs, and CMX compatibility testing.
• The example should follow the same conventions as existing examples in the repo.

Phase 2: Refine the Onboarding Agent Instructions

Work in the repl_claude_mktplc rig on branch add-replicated-onboarding-plugin.

Step 1: Triage gaps from Phase 1

• For every friction point, gap, or failure encountered in Phase 1, create a specific fix in the agent instructions.
• Common gap categories to watch for:
  • Agent handoff failures (Coding agent doesn't signal Review agent, or vice versa)
  • Missing context about complex chart structures (subcharts, dependencies, CRDs)
  • Incorrect assumptions about chart packaging or values
  • Missing steps in the onboarding workflow
  • Review agent unable to validate specific success criteria
  • Unclear or ambiguous instructions that caused the Coding agent to go off-track

Step 2: Implement fixes and validate with linting

• After each fix to the agent instructions, run:

  ailloy lint

  and

  ailloy assay

• There must be zero errors, zero warnings, and zero hints. If any appear, fix them before moving on.

• This is its own feedback loop: edit instructions → lint → fix lint issues → lint again → until clean.

Step 3: Reinstall and verify the plugin locally

• The README in the add-replicated-onboarding-plugin branch has instructions for:
  1. Installing the claude marketplace locally
  2. Installing the onboarding plugin locally
• After iterating on the agent instructions, follow these instructions to reinstall the plugin locally.
• Verify the plugin installs correctly.
• This makes the updated instructions apply to any new claude sessions, which serves as the final integration test.

Step 4: Re-run onboarding with refined instructions (if needed)

• If the gaps found in Phase 1 were significant, consider re-running the onboarding of GitLab (or a subset of it) using the refined agent instructions to confirm the fixes work end-to-end.

Orchestration Notes for the Mayor

Convoy structure

Create a convoy for each phase. Within each convoy, create beads for the major work units. Suggested breakdown:

Convoy 1: "GitLab Platform Example"

• Bead: Research existing examples and GitLab chart structure
• Bead: Run onboarding agents on GitLab charts (Coding → Review loop)
• Bead: Finalize and validate GitLab example in CMX
• Bead: Document all gaps/friction encountered (output for Phase 2)

Convoy 2: "Refine Onboarding Plugin"

• Bead: Triage and categorize Phase 1 gaps
• Bead: Fix agent instructions (with lint loop)
• Bead: Reinstall plugin locally and verify
• Bead: Optional re-run validation

Cross-rig coordination

• Phase 1 produces a gap report that feeds into Phase 2. Use the mailbox system to pass this between rigs.
• If during Phase 1, the Coding → Review loop breaks down in a way that's clearly an agent instruction bug (not a GitLab-specific issue), you may choose to context-switch to the repl_claude_mktplc rig to fix the instruction immediately, then return to repl_examples to continue. Use your judgment on whether to batch fixes or fix inline.

Agent spawning guidance

• For Phase 1 implementation work: spawn polecats in repl_examples. The onboarding agents (Coding and Review) are invoked through the globally installed instructions — the polecats just need to follow them.
• For Phase 2 instruction editing: spawn polecats in repl_claude_mktplc on branch add-replicated-onboarding-plugin.
• For lint validation: a dedicated polecat in repl_claude_mktplc can run the ailloy lint / ailloy assay loop.

Success criteria

1. GitLab platform example exists in repl_examples with working CI/CD workflows, Replicated SDK, and CMX validation — following existing repo conventions.
2. GitLab application is confirmed running in CMX.
3. Onboarding agent instructions in repl_claude_mktplc pass ailloy lint and ailloy assay with zero errors, warnings, or hints.
4. Onboarding plugin installs cleanly via the local install process documented in the branch README.
5. The Coding → Review feedback loop in the onboarding agents works naturally for a complex platform like GitLab — if it didn't initially, the instructions have been fixed so it would on a re-run.

Begin

Start with Phase 1. Create the convoys, research the existing patterns and GitLab chart structure, then use the onboarding agents to implement the GitLab platform example. Track everything — every gap you find is fuel for Phase 2.

[jmboby]

I noticed the release is helm-cli only when using 'make release', there are no EC or KOTS manifests

When you use --chart the Replicated CLI creates a Helm CLI-only release. The KOTS manifests in kots/ are never included.

To make it a KOTS-enabled release, you need to change chart to --yaml-dir pointing to your KOTS manifests:

replicated release create
--app $(REPLICATED_APP)
--yaml-dir kots
--release-notes "Release via Makefile"

The other gotcha is that it expects the gitlab-0.1.0.tgz chart from the previous cmd 'make package' to be in the /kots dir also, so maybe change the target for the 'make package' command?

I would include the promote flag in the release target also just to save a manual step:
--promote Unstable \

[jmboby]

I'm seeing a 'failed to render archive directory' in the KOTS Admin Console when testing out via CMX - Embedded cluster, did it work for you?

For some reason VP is also failing to see your HelmChart CR also, I do see the yaml manifest there however...

[kriscoleman]

I have made some updates but got pulled into a support issue today and couldn't finish UAT
looks like it needs a rebase too