Skip to content

ADR-0015: Retain GitHub + Linear + Jenkins as the Engineering Stack; Adopt KeyMate AI/Automation Patterns Without Tooling Migration

  • Status: ✅ Accepted
  • Date: 2026-05-22
  • Owners: @ozcan, @osmanç

Context

The KeyMate team operates entirely on GitLab and has built a mature AI-driven automation pipeline around it: SonarQube triggers automatic issue creation, Gemini Pro produces auto-fix merge requests, Gemini Flash performs review, and SonarQube closes the loop once the finding is resolved. KeyMate also relies on Renovate for dependency upgrades, OWASP and SonarQube quality gates inside the pipeline, GitLab Triage for scheduled pipeline workflows, and an OpenTelemetry + SigNoz observability stack.

Appcircle currently operates on GitHub + Linear + Jenkins. The question raised in cross-team discussions is whether Appcircle should consolidate on GitLab — matching KeyMate — or whether the underlying AI and automation patterns can be adopted on the existing stack with lower risk.

This ADR records the evaluation and the recommended direction.

Note

This ADR is not a judgment on GitLab as a platform. The goal is to assess whether a full migration is the right vehicle for adopting KeyMate's automation patterns inside Appcircle.

Decision

Appcircle will remain on its current GitHub + Linear + Jenkins stack.

Instead of migrating tooling, the team will import KeyMate's AI and automation patterns (auto-fix loops, code-quality–driven issue creation, automated dependency upgrades, modern observability) onto the existing stack. The Linear ↔ GitHub integration will be strengthened to provide equivalent capability at lower migration risk.

A follow-up ADR will be opened once the AI/automation rollout on GitHub is scoped concretely.

Warning

This decision intentionally avoids a platform migration. Adopting KeyMate's patterns still requires deliberate design and rollout work on the Appcircle side — the capability does not arrive automatically.

Options Considered

Option A — Migrate to GitLab to align with KeyMate (Rejected)

Pros

  • Single source of truth across both teams for issues, code review, dependency upgrades, and auto-fix workflows.
  • Direct reuse of KeyMate's mature loop: SonarQube → automatic issue → Gemini Pro auto-fix → Gemini Flash review → SonarQube closure.
  • Built-in Renovate, SonarQube, and OWASP integrations available as pipeline standards.
  • Centralized pipeline scheduling via GitLab Triage.
  • Modern observability via OpenTelemetry + SigNoz already in place.
  • Repo-level issue tracking enables cleaner per-repository metrics (regression rate, feature throughput, issue density).

Cons

  • Self-hosted customer runner whitelists. Self-hosted customers run runners inside their own data centers and have whitelisted github.com/appcircle at the network layer. Migration would require per-customer GitLab URL approval — a long, risky coordination cycle that can break runners during cutover.
  • Domain-level whitelists at github.com. Some customers can only whitelist domains, not paths. This is already a known security concern; migration carries the same constraint over to GitLab. A self-hosted GitLab Enterprise instance could address it, but introduces additional operational cost and overhead.
  • ac-script-self-hosted repository criticality. Every branch and its per-customer mapping would need to be migrated without loss. A single mismatch directly breaks a self-hosted customer.
  • Server-side self-hosted permissions. Whitelist requirements are not limited to runners — server components may also issue outbound requests to GitHub. A full inventory and a customer-side approval cycle would be required before any cutover.
  • Linear history loss. A significant portion of issue and ticket history would not survive the migration, weakening historical traceability.
  • User management overhead. All Linear users would need to be re-provisioned on GitLab, with additional operational load and licensing cost after the two-year free tier.
  • Jenkins → GitLab CI/CD migration risk. One-to-one pipeline replication is not guaranteed; unexpected breakage is likely. A PoC would be mandatory and adds effort. Dual-system operation during the transition is unavoidable and reduces productivity.
  • Public repository visibility. Appcircle currently maintains a large number of public repositories on GitHub. Moving them to GitLab would degrade community reach and external integration paths.
  • Single source of truth violated in practice. Runners occasionally fetch from GitHub public repositories. If that dependency remains after migration, the "single platform" claim is already broken.
  • Submodule dependencies. Several public repositories are used as submodules. Every submodule reference would need to be updated to point at GitLab — an additional breakage surface.
  • NuGet package migration. NuGet versions currently hosted on GitHub would need to move to the GitLab Package Registry, and Jenkins builds would need to be redirected to the new feed.
  • Maturity ramp-up time. The Linear + Jenkins combination is currently mature and productive. Reaching equivalent productivity on GitLab would take meaningful time and create a productivity dip during the transition.
  • Team signal. The team has expressed that the current stack is already strong. The concrete benefit of replacing a working setup is not clear.

Option B — Stay on GitHub + Linear + Jenkins; adopt KeyMate's AI/automation patterns on the existing stack (Selected)

Pros

  • Avoids all self-hosted customer whitelist coordination risks.
  • Preserves Linear history, existing Jenkins pipelines, public repository visibility, submodule references, and NuGet feed addresses.
  • The majority of KeyMate's capability gains (auto-fix, automated dependency upgrades, code-quality–driven issue creation, modern observability) can be reproduced on GitHub + Linear + Jenkins with significantly lower effort.
  • Strengthening the Linear ↔ GitHub integration (for example, AI-driven issue creation and an auto-fix PR flow) is a lower-risk, higher-ROI investment than a platform migration.

Cons

  • Each KeyMate pattern must be re-implemented on top of GitHub + Linear + Jenkins; this is not a free transfer.
  • Long-term cross-team alignment with KeyMate at the tooling layer is not pursued — alignment remains at the pattern level only.

Consequences

Positive

  • Self-hosted customer runners remain stable; no whitelist coordination cycle is triggered.
  • Linear ticket history, Jenkins pipelines, public repositories, submodules, and NuGet feeds remain untouched.
  • Engineering effort is focused on importing capabilities rather than rebuilding tooling.
  • The team retains a mature, working stack while gaining KeyMate's automation patterns incrementally.

Negative / Trade-offs

  • KeyMate's patterns must be designed and operated on the existing stack; this is implementation work, not a one-time platform switch.
  • Cross-team tooling alignment with KeyMate is only partial. Pattern-level alignment must be maintained deliberately over time.

Follow-ups

  1. Inventory the KeyMate AI/automation capabilities that Appcircle wants to import, with owners and target dates.
  2. Strengthen the Linear ↔ GitHub integration:
    • AI-driven automatic issue creation from code-quality and security findings.
    • Auto-fix PR flow comparable to KeyMate's Gemini Pro / Gemini Flash loop.
  3. Evaluate Renovate (or an equivalent) for automated dependency upgrades on Appcircle repositories.
  4. Evaluate SonarQube and OWASP integration inside the existing Jenkins pipelines.
  • Impacted components: GitHub organization, Linear workspace, Jenkins pipelines, self-hosted customer runner whitelists, ac-script-self-hosted repository, NuGet feeds, submodule references
  • Supersedes / Superseded by: N/A