Skip to content

Commit 17af756

Browse files
kriscolemanclaude
kriscoleman
and
claude
committed
feat: add GitLab platform example with Replicated onboarding (re-o64)
Adds a complete applications/gitlab/ example following existing repo conventions (gitea, n8n pattern). Includes: - Wrapper Helm chart with upstream gitlab 9.0.2 + Replicated SDK 1.18.0 - KOTS manifests: kots-app, kots-config (PostgreSQL/Redis/MinIO/SMTP), HelmChart with optionalValues, EC extensions, Secrets for passwords - GitHub Actions CI: lint/template on PR, create-release to Unstable on PR, promote to Stable on main merge - Makefile targets: add-helm-repositories, update-dependencies, lint, package - tests/helm/ci-values.yaml for fast CI lint/template checks - ONBOARDING-GAPS.md documenting 8 friction points from the onboarding run CMX validation skipped: no credits on REPL_GITLAB_SA_TOKEN account. Release 1 created and promoted to Unstable on gitlab-pika app. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 18cbc23 commit 17af756

16 files changed

Lines changed: 1007 additions & 0 deletions

File tree

‎.github/workflows/gitlab-ci.yml‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
name: GitLab CI
2+
3+
# Security note: REPLICATED_API_TOKEN must be from a dedicated service account,
4+
# NOT a personal token. Create one at: vendor.replicated.com >
5+
# Account Settings > Service Accounts.
6+
7+
on:
8+
pull_request:
9+
paths:
10+
- 'applications/gitlab/charts/**'
11+
- 'applications/gitlab/tests/**'
12+
- 'applications/gitlab/Makefile'
13+
- '.github/workflows/gitlab-ci.yml'
14+
push:
15+
branches:
16+
- main
17+
paths:
18+
- 'applications/gitlab/charts/**'
19+
- 'applications/gitlab/tests/**'
20+
- 'applications/gitlab/Makefile'
21+
- '.github/workflows/gitlab-ci.yml'
22+
23+
env:
24+
APP_SLUG: gitlab-pika
25+
26+
jobs:
27+
lint-and-template:
28+
runs-on: ubuntu-22.04
29+
defaults:
30+
run:
31+
working-directory: applications/gitlab
32+
steps:
33+
- name: Checkout
34+
uses: actions/checkout@v4
35+
36+
- name: Set up Helm
37+
uses: azure/setup-helm@v4.3.0
38+
with:
39+
version: v3.13.3
40+
41+
- name: Add Helm repositories
42+
run: make add-helm-repositories
43+
44+
- name: Update dependencies
45+
run: make update-dependencies
46+
47+
- name: Helm lint
48+
run: helm lint ./charts/gitlab
49+
50+
- name: Helm template (default values)
51+
run: helm template gitlab ./charts/gitlab > /dev/null
52+
53+
- name: Helm template (CI test values)
54+
run: helm template gitlab ./charts/gitlab -f tests/helm/ci-values.yaml > /dev/null
55+
56+
create-release:
57+
if: github.event_name == 'pull_request'
58+
runs-on: ubuntu-22.04
59+
needs: [lint-and-template]
60+
defaults:
61+
run:
62+
working-directory: applications/gitlab
63+
steps:
64+
- name: Checkout
65+
uses: actions/checkout@v4
66+
with:
67+
fetch-depth: 0
68+
69+
- name: Set up Helm
70+
uses: azure/setup-helm@v4.3.0
71+
with:
72+
version: v3.13.3
73+
74+
- name: Set release version
75+
id: set-release-version
76+
run: |
77+
git_hash=$(git rev-parse --short HEAD)
78+
version="pr-${{ github.event.pull_request.number }}-${git_hash}"
79+
echo "VERSION=${version}" >> $GITHUB_ENV
80+
81+
- name: Add Helm repositories
82+
run: make add-helm-repositories
83+
84+
- name: Package Helm chart
85+
run: helm package ./charts/gitlab --version ${{ env.VERSION }} -u
86+
87+
- name: Create Replicated release on Unstable
88+
uses: replicatedhq/compatibility-actions/create-release@v1
89+
with:
90+
app-slug: ${{ env.APP_SLUG }}
91+
api-token: ${{ secrets.REPLICATED_API_TOKEN }}
92+
chart: gitlab-${{ env.VERSION }}.tgz
93+
version: ${{ env.VERSION }}
94+
release-notes: "PR #${{ github.event.pull_request.number }} - ${{ github.event.pull_request.title }}"
95+
promote-channel: Unstable
96+
97+
promote-stable:
98+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
99+
runs-on: ubuntu-22.04
100+
needs: [lint-and-template]
101+
defaults:
102+
run:
103+
working-directory: applications/gitlab
104+
steps:
105+
- name: Checkout
106+
uses: actions/checkout@v4
107+
with:
108+
fetch-depth: 0
109+
110+
- name: Set up Helm
111+
uses: azure/setup-helm@v4.3.0
112+
with:
113+
version: v3.13.3
114+
115+
- name: Set release version
116+
id: set-release-version
117+
run: |
118+
git_hash=$(git rev-parse --short HEAD)
119+
date_version=$(date -u '+%Y.%-m.%-d-%H%M%S')
120+
version="${date_version}-${git_hash}"
121+
echo "VERSION=${version}" >> $GITHUB_ENV
122+
123+
- name: Add Helm repositories
124+
run: make add-helm-repositories
125+
126+
- name: Package Helm chart
127+
run: helm package ./charts/gitlab --version ${{ env.VERSION }} -u
128+
129+
- name: Create release and promote to Stable
130+
uses: replicatedhq/compatibility-actions/create-release@v1
131+
with:
132+
app-slug: ${{ env.APP_SLUG }}
133+
api-token: ${{ secrets.REPLICATED_API_TOKEN }}
134+
chart: gitlab-${{ env.VERSION }}.tgz
135+
version: ${{ env.VERSION }}
136+
release-notes: "Merged to main - ${{ github.sha }}"
137+
promote-channel: Stable

‎applications/gitlab/Makefile‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
.PHONY: add-helm-repositories update-dependencies lint package release
2+
3+
CHART_DIR := charts/gitlab
4+
APP_SLUG := gitlab-pika
5+
6+
add-helm-repositories:
7+
helm repo add gitlab https://charts.gitlab.io/
8+
helm repo update
9+
10+
update-dependencies:
11+
helm dependency update $(CHART_DIR)
12+
13+
lint:
14+
helm lint $(CHART_DIR)
15+
helm template gitlab $(CHART_DIR) > /dev/null
16+
helm template gitlab $(CHART_DIR) -f tests/helm/ci-values.yaml > /dev/null
17+
18+
package: update-dependencies
19+
helm package $(CHART_DIR)
20+
21+
release: package
22+
REPLICATED_API_TOKEN=$(REPLICATED_API_TOKEN) replicated release create \
23+
--app $(APP_SLUG) \
24+
--chart gitlab-*.tgz \
25+
--release-notes "Release via Makefile"

‎applications/gitlab/ONBOARDING-GAPS.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# GitLab Onboarding Gaps & Friction Log
2+
3+
This document captures gaps, friction points, and unclear instructions
4+
encountered while running the `replicated-onboarding` plugin on the GitLab
5+
Helm chart example. This feeds Phase 2 improvements to the plugin.
6+
7+
---
8+
9+
## Gap 1: `helm` not installed in polecat environment
10+
11+
**Skill**: `assess-repo`, `install-sdk`
12+
**Severity**: Blocker (self-resolved)
13+
**Description**: The `helm` binary was not in `PATH` on the polecat worker.
14+
The `assess-repo` skill calls `helm lint` and `install-sdk` calls
15+
`helm dependency update`, both of which failed with `command not found: helm`.
16+
**Resolution**: Installed via `brew install helm`. Took ~60s.
17+
**Recommendation**: The skill should detect missing `helm` and provide a
18+
one-line install command rather than failing silently. Or the polecat
19+
environment should have `helm` pre-installed.
20+
21+
---
22+
23+
## Gap 2: `replicated whoami` command does not exist
24+
25+
**Skill**: `create-release` (auth step references `@skills/shared/auth.md`)
26+
**Severity**: Minor friction
27+
**Description**: The skill doc references `replicated whoami` for auth
28+
verification, but `replicated` CLI v0.124.3 does not have a `whoami` command.
29+
The available command is `replicated login` or checking `replicated app ls`.
30+
**Resolution**: Used `replicated app ls` as an auth check.
31+
**Recommendation**: Update `@skills/shared/auth.md` to use `replicated app ls`
32+
or add a note about the CLI version difference.
33+
34+
---
35+
36+
## Gap 3: Replicated API token not clearly documented for automation
37+
38+
**Skill**: `create-release`
39+
**Severity**: Blocker (required Mayor escalation)
40+
**Description**: The task description said "auth via REPL_GITLAB_SA_TOKEN" but
41+
the `create-release` skill only references `@skills/shared/auth.md` which
42+
talks about a `REPLICATED_API_TOKEN` env var. The polecat did not know that
43+
`REPL_GITLAB_SA_TOKEN` was the Replicated API token — it looked like a GitLab
44+
token. Required escalation to Mayor to clarify.
45+
**Resolution**: `REPLICATED_API_TOKEN=$REPL_GITLAB_SA_TOKEN` prefix on commands.
46+
**Recommendation**: Task descriptions for onboarding should explicitly state
47+
which env var maps to `REPLICATED_API_TOKEN`. Or the skill should list which
48+
env vars it checks (e.g., `REPLICATED_API_TOKEN`, `REPL_*_SA_TOKEN`).
49+
50+
---
51+
52+
## Gap 4: `replicated release promote` requires `--app` flag (not positional)
53+
54+
**Skill**: `create-release`
55+
**Severity**: Minor friction
56+
**Description**: The skill doc shows:
57+
```bash
58+
replicated release promote <sequence> <app_slug>/Unstable --version <version>
59+
```
60+
But the actual CLI syntax is:
61+
```bash
62+
replicated release promote <sequence> Unstable --app <app_slug> --version <version>
63+
```
64+
The `<app_slug>/Unstable` format is not valid for this CLI version.
65+
**Resolution**: Used `--app gitlab-pika` flag separately.
66+
**Recommendation**: Update the skill doc to use the `--app` flag form, or
67+
document both syntaxes.
68+
69+
---
70+
71+
## Gap 5: CMX validation blocked — no credits on service account
72+
73+
**Skill**: `validate-cmx`
74+
**Severity**: Blocker (not self-resolvable)
75+
**Description**: Every `replicated cluster create` attempt — from `r1.small`
76+
to `r1.2xlarge` — failed with:
77+
```
78+
Error: Request exceeds available credits. Contact Replicated to buy more credits.
79+
```
80+
The REPL_GITLAB_SA_TOKEN service account has zero CMX credits.
81+
**Resolution**: Skipped CMX validation entirely per Mayor instruction.
82+
**CMX validation will need to run after credits are added to the account.**
83+
**Recommendation**: The `validate-cmx` skill has no guidance for the
84+
"zero credits" failure mode. It should detect this specific error message
85+
and instruct the agent to:
86+
1. Skip CMX validation
87+
2. Document the gap in ONBOARDING-GAPS.md
88+
3. Continue with the rest of the onboarding checklist
89+
Currently, an agent would retry all instance sizes (wasting time) before
90+
escalating. The skill should short-circuit on this error.
91+
92+
---
93+
94+
## Gap 6: GitLab chart resource requirements far exceed other examples
95+
96+
**Skill**: n/a (architecture gap)
97+
**Severity**: Informational
98+
**Description**: GitLab's minimum eval cluster (12 GB RAM, 4 vCPU) is
99+
significantly larger than other examples in this repo (gitea, n8n). The CMX
100+
`r1.medium` instance type is insufficient; `r1.large` or `r1.xlarge` is needed.
101+
**Recommendation**: Document minimum cluster requirements prominently in
102+
README. Consider adding a `ci-values.yaml` that uses heavily reduced resource
103+
requests for lint/template CI checks (which don't actually install the chart).
104+
105+
---
106+
107+
## Gap 7: `validate-cmx` skill uses `--version latest` which is invalid for k3s
108+
109+
**Skill**: `validate-cmx`
110+
**Severity**: Minor friction
111+
**Description**: The skill doc's example uses `--version latest` in the
112+
`replicated cluster create` command. But `k3s` does not support `latest` as
113+
a version string — it requires a specific version like `1.32`.
114+
**Resolution**: Used `--version 1.32` explicitly.
115+
**Recommendation**: Update skill example to use a specific version, or use
116+
`replicated cluster versions` output to select the latest available.
117+
118+
---
119+
120+
## Gap 8: HelmChart `optionalValues` pattern not validated during onboarding
121+
122+
**Skill**: n/a (plugin scope gap)
123+
**Severity**: Informational
124+
**Description**: The `configure-values` and `install-sdk` skills don't
125+
validate that the generated `HelmChart` kind's `optionalValues` are
126+
syntactically correct KOTS YAML. Errors only surface at deploy time.
127+
**Recommendation**: Add a linting step to `create-release` or a new
128+
`validate-kots-manifests` skill that runs `kots` CLI or schema validation
129+
against the generated manifests.
130+
131+
---
132+
133+
## Summary
134+
135+
| # | Gap | Severity | Skill |
136+
|---|-----|----------|-------|
137+
| 1 | `helm` not in PATH | Blocker (self-resolved) | assess-repo, install-sdk |
138+
| 2 | `replicated whoami` doesn't exist | Minor | create-release (auth) |
139+
| 3 | API token identity unclear | Blocker (escalated) | create-release |
140+
| 4 | `release promote` flag syntax wrong | Minor | create-release |
141+
| 5 | CMX: zero credits, no skip guidance | **Blocker (pending)** | validate-cmx |
142+
| 6 | GitLab resource requirements undocumented | Info | n/a |
143+
| 7 | `--version latest` invalid for k3s | Minor | validate-cmx |
144+
| 8 | KOTS manifests not linted | Info | n/a |

0 commit comments

Comments
 (0)