Repository navigation
Add GitLab CI as a trigger/coordination and compute layer #322
Description
What is missing
Fullsend currently only supports GitHub as both the forge (repo hosting) and the trigger/coordination and compute layer (GitHub Actions). To reach organizations that host code on GitLab, we need to support GitLab as a forge and GitLab CI as the corresponding trigger/compute backend.
The existing forge.Client interface (ADR-0005) provides a starting point for forge abstraction, but the installer's layer stack — workflows, shim templates, secrets, dispatch tokens, enrollment — has GitHub-specific logic baked into each layer. Supporting GitLab will require refactoring these layers so that forge-specific behavior is pluggable rather than hardcoded.
What should happen
- The installer can target a GitLab organization (group), creating the equivalent of the
.fullsendconfig repo, enrolling target projects with a.gitlab-ci.ymlshim, and provisioning CI/CD variables for credentials. - Agent dispatch uses GitLab CI pipelines triggered via the API, analogous to the current
workflow_dispatchmodel. - GitLab.com SaaS and self-managed GitLab instances are both in scope.
- E2E tests exercise the full install/uninstall flow against a GitLab.com test organization, mirroring the existing GitHub e2e tests.
- Trigger rules for each agent role (triage, code, review) are defined once in a forge-neutral format and compiled to forge-native formats (GitHub Actions YAML,
.gitlab-ci.yml). This prevents trigger rules from drifting between forges when one is updated and the other is forgotten.
Context
Composability model. Today, forge and trigger/compute are implicitly coupled: GitHub repos use GitHub Actions, and GitLab repos would use GitLab CI. This coupling is inherent — GitHub Actions can't receive event triggers from GitLab repos, and vice versa. However, the architecture should anticipate a future where a forge-agnostic trigger/compute layer (e.g., a Kubernetes-based webhook receiver launching agent pods) can pair with any forge. The refactoring done here should move toward independently composable forge and trigger/compute backends, even though the initial GitLab implementation will be a paired forge+compute unit like the existing GitHub one.
What's tightly coupled today. The following areas contain GitHub-specific assumptions that will need abstraction or parallel implementation:
- Event model — shim workflow listens for
issues,issue_comment,pull_request_target,pull_request_reviewevents - Dispatch mechanism —
workflow_dispatchvia fine-grained PAT withactions:write - Credential model — per-role GitHub Apps created via manifest flow
- Secrets layer — GitHub Actions repo secrets and org secrets
- Workflow templates — GitHub Actions YAML in
internal/scaffold/ - Agent wrappers — currently invoke GitHub-specific tooling (see Fully define agent wrappers and their interface with agents #101)
Preventing trigger rule drift across forges. Once the same agent role (e.g., review) has trigger rules defined in both GitHub Actions YAML and .gitlab-ci.yml, there's a real risk that a change to one is forgotten in the other. Possible mitigations, not mutually exclusive:
- Neutral trigger format that compiles to forge-native configs. Define trigger rules (which events, which conditions, which filters) in a single forge-agnostic representation. A code generator or template engine produces the GitHub Actions and GitLab CI YAML from that source of truth. This makes it structurally impossible to update one without the other.
- Equivalence-checking skill or test. A CI check, Claude Code skill, or both that compares the trigger configurations across forges and flags functional divergence. This catches drift even if someone edits a forge-native file directly.
- Review checklist enforcement. A CLAUDE.md instruction (and/or a PR review skill) that requires reviewers — human or agent — to verify trigger rule parity across all supported forges whenever trigger-related files are modified.
Which combination of these to adopt is an open question that should be decided before or during the implementation phases below.
Suggested phasing. This is large enough to warrant phased delivery. One possible breakdown:
- Refactor layers for backend pluggability — Extract forge-specific logic from the layer stack so that each layer delegates to a backend-specific implementation. This benefits all future backends, not just GitLab.
- Implement GitLab forge client — A
forge.Clientimplementation for the GitLab API covering repos, merge requests, labels, CI/CD variables, file operations, and project access tokens or equivalent credentials. - Implement GitLab CI trigger/compute layer —
.gitlab-ci.ymlshim for enrolled projects, pipeline trigger dispatch, credential model (project/group access tokens or OAuth apps), concurrency controls. - Installer CLI support for GitLab — CLI flow for targeting a GitLab group, including App/token creation, interactive setup, and configuration.
- E2E test infrastructure — GitLab.com test organization(s) for CI, Playwright-based or API-based e2e tests mirroring the GitHub e2e suite.
- Trigger rule parity guardrails — Neutral trigger format, equivalence checks, and/or review checklist items to prevent drift between forge-specific configurations.
This phasing is a suggestion, not a prescription — it may make sense to reorder or split differently as work progresses.
Related issues:
- Fully define agent wrappers and their interface with agents #101 — Fully define agent wrappers and their interface with agents (forge-agnostic agent interface)
- Story 1: Installation & Bootstrap #124 — Story 1: Installation & Bootstrap (current GitHub-specific install flow)
Activity
ralphbean commentedon Apr 22, 2026
Documentation and normative spec impact
Adding GitLab as a forge+compute backend has significant documentation implications. Several existing normative docs bake in GitHub-specific assumptions, and new normative docs are likely needed to make this a spec-forward change rather than an implementation that outpaces its specs.
Existing docs that need updates
ADRs with GitHub-specific assumptions:
dispatch.platformis hard-coded togithub-actions. A v2 schema needs to supportgitlab-ci(and eventually others).Normative specs that need updates or parallel versions:
.fullsendassumes GitHub Actions workflow YAML. GitLab equivalent needs specifying..gitlab-ci.ymlshim in enrolled projects) needs its own spec.Problem documents that use GitHub-specific language:
agent-architecture.md— References CODEOWNERS, GitHub issue lifecycle, PR workflowautonomy-spectrum.md— References CODEOWNERS as the approval-required-paths mechanismgovernance.md— References CODEOWNERS and GitHub branch protectioncode-review.md— References PR review semanticsThese should be updated to use forge-agnostic language (or at minimum note that the concepts have forge-specific implementations).
New normative docs likely needed
ADR: Multi-forge trigger and coordination model — Extends ADR 0002 to define how the event→label→dispatch state machine maps across forges. Covers webhook event schemas, label/tag semantics, slash command parsing, and status check equivalents for each supported forge.
ADR: Identity and credential provisioning for non-GitHub forges — Extends ADR 0007 to specify how per-role identity works on GitLab (and eventually Forgejo). Covers what replaces GitHub Apps, how secrets are scoped, and how credential isolation (ADR 0017) is maintained.
ADR: Cross-project dispatch for non-GitHub-Actions platforms — Extends ADR 0008 to specify how enrolled projects trigger agent pipelines in the config project on GitLab CI (pipeline triggers, CI/CD variables, cross-project pipelines).
Normative spec: config.yaml v2 schema — Extends ADR 0011 to make
dispatch.platforman enum, add forge-specific fields, and define how the config repo is identified per forge.Normative spec: Neutral trigger rule format — As discussed in the issue body, a spec for the forge-agnostic trigger rule representation that compiles to forge-native configs.
What's already forge-agnostic (no changes needed)
Recommendation
The normative work should lead the implementation, not follow it. Suggest writing at minimum ADRs for items 1-3 above before starting phase 1 (layer refactoring), so that the refactoring is guided by a clear target architecture rather than just "make it pluggable."
ascerra commentedon Apr 24, 2026
Meeting context (2026-04-24 optional sync): The team committed to testing GitLab integration and workflow mapping as soon as PR #390 (dispatch architecture) is done. Platform-dependence concerns were discussed: the risk of becoming too tied to GitHub workflows was raised, but the team agreed that workflows/shims are inherently platform-dependent, while agents and harnesses should remain platform-independent. The position was: agents and harnesses are portable; trigger/dispatch infrastructure is platform-native. The goal is to look like a "good citizen" on each platform, not to build a generic workflow system.
fullsend-ai-triage commentedon May 5, 2026
RICE Priority Score: 0.3
Score breakdown
Formula: (1 × 1.5 × 0.6) / 3 = 0.3
ggallen commentedon Jul 30, 2026
Superseded by ADR 0067 (GitLab cron-polling event dispatch). The core GitLab support is implemented under a different architecture than described here: cron-polling dispatch, per-repo CI templates (fullsend-agent.yml, fullsend-dispatch.yml, fullsend-poll.yml), WIF/OIDC credential model, and bot PAT via Secret Manager. Remaining GitLab work is tracked in specific issues (#5766, #5416, etc.).