CI/CD Flow Interpreter — Design Spec¶
Historical 1.x proposal: This specification is not a public 2.0 feature contract. See the current tool catalog, architecture, and roadmap.
Date: 2026-07-26
Target Release: v1.2.0
Status: Draft
Priority: P2 (HIGH value, LOW-MEDIUM effort)
Author: Architecture profile (Phase 1 research), mcp-server-jvm-build-tools
1. Overview / Motivation¶
Developers commonly need to set up CI/CD pipelines for their JVM projects, but writing multi-platform CI configurations (GitHub Actions, GitLab CI, Jenkins) is error-prone, especially when the pipeline must account for build-tool-specific nuances (Maven wrapper vs. Gradle wrapper caching, SBT parallel testing, JDK matrix strategies).
CI/CD Flow Interpreter lets an agent describe a pipeline in natural language and receive a validated, build-tool-aware CI configuration file. This eliminates the trial-and-error cycle of writing, committing, pushing, and debugging CI YAML.
Key Design Goals¶
- Natural-language ingress — "Set up CI that runs tests on every push, builds on PR, deploys on tag" → generated YAML.
- Build-tool-aware generation — generated pipelines use the correct commands for Maven (
mvn verify), Gradle (./gradlew build), and SBT (sbt test). - Validation — generated YAML is syntax-checked and validated for required fields (on trigger, job name, runner, steps).
- As MVP: GitHub Actions only — but the architecture supports adding GitLab CI, Jenkins, CircleCI, etc. via a
CicdTargetinterface.
2. Design Decisions¶
Decision 1: Output format — GitHub Actions YAML MVP, extensible¶
Chosen: GitHub Actions as the initial (MVP) target, with an interface for future targets.
| Target | Phase | Priority |
|---|---|---|
| GitHub Actions | v1.2.0 (MVP) | P0 — ~80% of OSS JVM projects use this |
| GitLab CI | v1.3.0 | P1 |
| Jenkinsfile | v1.4.0 | P2 |
Rationale: Phase 1 competitive research (docs/competitive-landscape-july-2026.md) shows that 13 new JVM MCP servers have appeared since June 2026, but none offer CI/CD config generation. This is a clear differentiator for the project's 3-build-tool support.
The interface CicdTarget abstracts the generation strategy so new targets can be added without changing the core interpretation logic.
Decision 2: Generation only (MVP), generation + validation later¶
Chosen: Generation first; validation of existing CI configs added in v1.3.0.
For v1.2.0, the tool generates a complete CI configuration from scratch. Validation (read-only analysis of existing configs) extends the tool in a follow-up release. This keeps the MVP scope tight and avoids the complexity of parsing existing CI YAML from diverse sources.
Decision 3: Template-based generation with dynamic parameterization¶
Chosen: Hybrid approach — templates for common pipeline shapes, dynamic for custom flows.
- Pipeline shapes (predefined):
ci-push,ci-pr,ci-release,ci-full(push+PR+release). - Templates encode best practices for each build tool:
- Maven:
mvn verifywithactions/setup-java, wrapper caching, JDK matrix. - Gradle:
./gradlew buildwith Gradle cache, wrapper validation, JDK matrix. - SBT:
sbt testwith Coursier cache, JDK matrix, parallel execution. - Custom flows are assembled dynamically when the description doesn't match a predefined shape.
Decision 4: Template library in /cicd/templates/¶
Templates are stored as resource files in src/main/resources/cicd/templates/ and loaded at startup. They use a simple {{PLACEHOLDER}} substitution system (not a full template engine, to avoid additional dependencies).
Decision 5: Secret management — placeholder injection¶
Generated CI configs use ${{ secrets.XXX }} placeholders for secrets. The tool documents the required secrets (e.g., DEPLOY_KEY, MAVEN_SETTINGS, DOCKER_PASSWORD) and the agent or user creates them in the CI provider's UI.
3. Pipeline Data Model¶
3.1 CicdPipeline — Intermediate Representation¶
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "CicdPipeline",
"description": "Intermediate representation of a CI/CD pipeline",
"type": "object",
"required": ["name", "target", "on", "jobs"],
"properties": {
"name": {
"type": "string",
"description": "Pipeline name (e.g., 'CI', 'Build and Test')"
},
"target": {
"type": "string",
"enum": ["github-actions"],
"description": "CI/CD platform target"
},
"description": {
"type": "string",
"description": "Original natural language description"
},
"on": {
"type": "object",
"description": "Trigger configuration",
"properties": {
"push": {
"type": "object",
"properties": {
"branches": {
"type": "array",
"items": { "type": "string" },
"default": ["main"]
},
"paths": {
"type": "array",
"items": { "type": "string" }
}
}
},
"pull_request": {
"type": "object",
"properties": {
"branches": {
"type": "array",
"items": { "type": "string" }
}
}
},
"release": {
"type": "object",
"properties": {
"types": {
"type": "array",
"items": { "type": "string", "enum": ["created", "published", "released"] }
}
}
},
"schedule": {
"type": "array",
"items": {
"type": "object",
"properties": {
"cron": { "type": "string" }
}
}
},
"workflow_dispatch": {
"type": "object"
}
}
},
"env": {
"type": "object",
"description": "Environment variables shared across all jobs",
"additionalProperties": { "type": "string" }
},
"defaults": {
"type": "object",
"description": "Default settings for all jobs",
"properties": {
"shell": { "type": "string", "default": "bash" },
"working-directory": { "type": "string" }
}
},
"jobs": {
"type": "array",
"description": "Ordered list of CI jobs",
"items": {
"$ref": "#/$defs/CicdJob"
}
},
"permissions": {
"type": "object",
"description": "Workflow-level permissions",
"properties": {
"contents": { "type": "string", "enum": ["read", "write", "none"] },
"issues": { "type": "string", "enum": ["read", "write", "none"] },
"pull-requests": { "type": "string", "enum": ["read", "write", "none"] },
"packages": { "type": "string", "enum": ["read", "write", "none"] },
"id-token": { "type": "string", "enum": ["read", "write", "none"] }
}
},
"requiredSecrets": {
"type": "array",
"description": "Secrets that must be configured in the CI provider",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"description": { "type": "string" }
}
}
}
},
"$defs": {
"CicdJob": {
"type": "object",
"required": ["name", "runsOn", "steps"],
"properties": {
"name": { "type": "string" },
"id": { "type": "string", "description": "Job identifier for the target format" },
"runsOn": {
"type": "string",
"description": "Runner type (e.g., 'ubuntu-latest', 'windows-latest')",
"default": "ubuntu-latest"
},
"needs": {
"type": "array",
"items": { "type": "string" },
"description": "Job dependencies"
},
"strategy": {
"type": "object",
"properties": {
"matrix": {
"type": "object",
"properties": {
"java": {
"type": "array",
"items": { "type": "string" },
"description": "JDK versions (e.g., ['21', '23'])"
},
"os": {
"type": "array",
"items": { "type": "string" }
}
}
},
"fail-fast": {
"type": "boolean",
"default": true
}
}
},
"steps": {
"type": "array",
"items": {
"$ref": "#/$defs/CicdStep"
}
},
"env": {
"type": "object",
"additionalProperties": { "type": "string" }
},
"timeoutMinutes": {
"type": "integer",
"default": 60
},
"condition": {
"type": "string",
"description": "Job condition (e.g., 'github.ref == refs/heads/main')"
}
}
},
"CicdStep": {
"type": "object",
"required": ["name"],
"properties": {
"name": { "type": "string" },
"uses": {
"type": "string",
"description": "Action reference (e.g., 'actions/checkout@v4')"
},
"run": {
"type": "string",
"description": "Shell command to execute"
},
"with": {
"type": "object",
"description": "Action parameters",
"additionalProperties": true
},
"env": {
"type": "object",
"additionalProperties": { "type": "string" }
},
"if": {
"type": "string",
"description": "Step condition"
},
"continue-on-error": {
"type": "boolean",
"default": false
},
"timeoutMinutes": {
"type": "integer"
},
"workingDirectory": {
"type": "string"
}
}
}
}
}
3.2 Java Records¶
// New file: src/main/java/com/pragmatik/buildtools/cicd/CicdPipeline.java
public record CicdPipeline(
String name,
String target, // "github-actions" (MVP)
String description,
CicdTrigger on,
Map<String, String> env,
@Nullable CicdDefaults defaults,
List<CicdJob> jobs,
@Nullable CicdPermissions permissions,
List<CicdSecret> requiredSecrets,
String detectedBuildTool // auto-detected or specified
) {}
// New file: src/main/java/com/pragmatik/buildtools/cicd/CicdTrigger.java
public record CicdTrigger(
@Nullable CicdPushTrigger push,
@Nullable CicdPrTrigger pullRequest,
@Nullable CicdReleaseTrigger release,
List<CicdScheduleTrigger> schedule,
boolean workflowDispatch
) {}
// New file: src/main/java/com/pragmatik/buildtools/cicd/CicdJob.java
public record CicdJob(
String name,
String id,
String runsOn, // default: "ubuntu-latest"
List<String> needs,
@Nullable CicdMatrixStrategy strategy,
List<CicdStep> steps,
Map<String, String> env,
int timeoutMinutes, // default: 60
@Nullable String condition
) {}
// New file: src/main/java/com/pragmatik/buildtools/cicd/CicdStep.java
public record CicdStep(
String name,
@Nullable String uses,
@Nullable String run,
Map<String, Object> with,
Map<String, String> env,
@Nullable String condition,
boolean continueOnError,
@Nullable Integer timeoutMinutes,
@Nullable String workingDirectory
) {}
// New file: src/main/java/com/pragmatik/buildtools/cicd/CicdTarget.java
public interface CicdTarget {
String name(); // e.g., "github-actions"
String generate(CicdPipeline pipeline); // Intermediate → target YAML/String
boolean validate(String configContent); // Syntax + required-fields check
}
// New file: src/main/java/com/pragmatik/buildtools/cicd/GitHubActionsTarget.java
@Component
public class GitHubActionsTarget implements CicdTarget {
// Generates .github/workflows/{name}.yml from CicdPipeline IR
}
3.3 Pipeline Shapes (Predefined Templates)¶
# Template: ci-push.yml
# Trigger: push to main
name: CI - {{NAME}}
on:
push:
branches: [{{BRANCHES}}]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
java: [{{JAVA_VERSIONS}}]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-java@v4
with:
distribution: 'temurin'
java-version: ${{ matrix.java }}
{{CACHE_CONFIG}}
- name: Build with {{TOOL_NAME}}
run: {{BUILD_COMMAND}}
4. API / Tool Definitions¶
4.1 interpret_ci_flow (New Tool)¶
Interpret a natural language CI/CD description and generate a pipeline configuration.
@Tool(
name = "interpret_ci_flow",
description = "Interpret a natural-language CI/CD pipeline description and "
+ "generate a validated configuration file. Supports GitHub Actions (MVP). "
+ "Returns the generated YAML, validation status, detected build tool, "
+ "required secrets, and a pipeline summary."
)
public String interpretCiFlow(
@ToolParam(required = true,
description = "Natural language description of the CI/CD pipeline, "
+ "e.g. 'Set up CI that runs tests on every push to main, builds on "
+ "PR, and deploys on release tag'")
String description,
@ToolParam(required = false,
description = "CI/CD target platform. Default: 'github-actions'. "
+ "Future: 'gitlab-ci', 'jenkins'.")
String target,
@ToolParam(required = false,
description = "Project directory for build-tool detection "
+ "(auto-detects Maven, Gradle, or SBT)")
String projectDir,
@ToolParam(required = false,
description = "Build tool override: 'maven', 'gradle', or 'sbt'")
String buildToolName,
@ToolParam(required = false,
description = "Pipeline shape hint: 'ci-push', 'ci-pr', 'ci-release', "
+ "'ci-full', or 'custom' (default: auto-detect from description)")
String pipelineShape,
@ToolParam(required = false,
description = "JDK versions to test against (comma-separated). "
+ "Default derived from project Java configuration. "
+ "Examples: '21', '21,23', '17,21,23'")
String javaVersions,
@ToolParam(required = false,
description = "Additional configuration overrides as JSON. "
+ "Examples: {\"runners\": [\"ubuntu-latest\"], "
+ "\"timeout\": 30, \"branches\": [\"main\", \"develop\"]}")
String configOverrides
);
Returns: Pipeline generation result JSON.
{
"pipelineName": "CI - my-project",
"target": "github-actions",
"detectedBuildTool": "maven",
"validation": {
"valid": true,
"warnings": []
},
"requiredSecrets": [
{"name": "DEPLOY_KEY", "description": "SSH key for deployment"},
{"name": "MAVEN_SETTINGS", "description": "Maven settings.xml with server credentials"}
],
"pipelineSummary": {
"triggers": ["push to main", "pull_request", "release published"],
"jobs": [
{"name": "Build", "runsOn": "ubuntu-latest", "matrix": ["21", "23"]},
{"name": "Test", "needs": ["build"]},
{"name": "Deploy", "needs": ["test"], "condition": "startsWith(github.ref, 'refs/tags/v')"}
],
"totalSteps": 10
},
"config": "# Generated by mcp-server-jvm-build-tools v1.2.0\n... full YAML ...",
"suggestedPath": ".github/workflows/ci.yml"
}
4.2 validate_ci_config (New Tool)¶
Validate an existing CI configuration for syntax and build-tool compatibility.
@Tool(
name = "validate_ci_config",
description = "Validate an existing CI/CD configuration file for syntax "
+ "correctness and build-tool compatibility. Checks YAML validity, "
+ "required field presence, and build-tool-specific command alignment. "
+ "Does NOT execute any commands — read-only analysis."
)
public String validateCiConfig(
@ToolParam(required = true,
description = "Raw CI configuration file content")
String configContent,
@ToolParam(required = false,
description = "CI/CD target platform: 'github-actions' (default)")
String target,
@ToolParam(required = false,
description = "Build tool for compatibility check: 'maven', 'gradle', "
+ "or 'sbt'")
String buildToolName
);
5. Generation Strategy¶
5.1 Pipeline Shape Detection¶
The interpret_ci_flow tool uses a keyword-matching algorithm on the description to determine the pipeline shape:
| Keywords | Shape | Jobs Generated |
|---|---|---|
push, commit | ci-push | Build + Test |
pr, pull request, review | ci-pr | Build + Test (PR trigger only) |
deploy, release, publish, tag | ci-release | Build + Test + Deploy |
push + pr + release | ci-full | Build + Test + Deploy (all triggers) |
| (none specific) | ci-push (default) | Build + Test |
5.2 Build-Tool-Specific Patterns¶
| Build Tool | Setup Step | Build Command | Cache Key | Test Command |
|---|---|---|---|---|
| Maven | setup-java@v4 | mvn verify -B | maven-{{ checksum "pom.xml" }} | mvn test -B |
| Gradle | setup-java@v4 + gradle/actions/setup-gradle | ./gradlew build | gradle-{{ checksum "**/*.gradle*" }} | ./gradlew test |
| SBT | setup-java@v4 + Coursier cache | sbt test | sbt-{{ checksum "build.sbt" }} | sbt test |
5.3 JDK Matrix Strategy¶
When the project has a pom.xml with <maven.compiler.release>21</maven.compiler.release>, the generated matrix includes: - 21 (project minimum) - 23 (latest stable if discovered from system) - Optionally 25 (early-access, if user specifies)
When the project is Gradle or SBT, the matrix defaults to ['21', '23'] unless javaVersions is explicitly provided.
5.4 Cache Configuration¶
Each build-tool target generates optimal cache configuration:
Maven:
- name: Cache Maven dependencies
uses: actions/cache@v4
with:
path: ~/.m2/repository
key: maven-${{ hashFiles('**/pom.xml') }}
restore-keys: maven-
Gradle:
- name: Cache Gradle packages
uses: actions/cache@v4
with:
path: |
~/.gradle/caches
~/.gradle/wrapper
key: gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
restore-keys: gradle-
SBT:
- name: Cache Coursier / SBT
uses: actions/cache@v4
with:
path: |
~/.cache/coursier
~/.sbt
key: sbt-${{ hashFiles('build.sbt', 'project/**') }}
restore-keys: sbt-
6. Validation Approach¶
What Gets Validated¶
| Check | What It Does |
|---|---|
| YAML syntax | Parses the generated YAML. Reports line:column errors. |
| Required fields | Ensures name, on, jobs[].runs-on, jobs[].steps are present. |
| Trigger validity | Verifies on.push.branches is non-empty; on.schedule.cron is valid. |
| Step uniqueness | Checks for duplicate step names within a job. |
| Build-tool commands | Verifies that all run commands use allowlisted build tool commands. |
| Action references | Validates uses: references follow {owner}/{repo}@{ref} format. |
What's NOT Validated (Out of Scope for MVP)¶
- Actual workflow runtime correctness (e.g., does the workflow file actually run?)
- GitHub Actions expression syntax (
${{ }}) beyond basic presence checking. - Composite action internals.
- Self-hosted runner availability.
7. Error Handling¶
| Scenario | Behaviour |
|---|---|
| Unknown build tool | Returns error with detected project files; asks user to specify |
| Empty description | Returns error: "CI description is required" |
| Invalid target name | Returns error: "Unknown target 'gitlab-ci'. Supported: github-actions" |
| YAML generation failure | Returns error with last good intermediate representation for debugging |
| Template not found for shape | Falls back to dynamic generation from intermediate representation |
| Validation warning | Returns config with warnings embedded; does NOT prevent generation |
8. Implementation Plan¶
Files to Create¶
| File | Purpose |
|---|---|
src/main/java/com/pragmatik/buildtools/cicd/CicdPipeline.java | Pipeline IR record |
src/main/java/com/pragmatik/buildtools/cicd/CicdTrigger.java | Trigger configuration |
src/main/java/com/pragmatik/buildtools/cicd/CicdJob.java | Job definition |
src/main/java/com/pragmatik/buildtools/cicd/CicdStep.java | Step definition |
src/main/java/com/pragmatik/buildtools/cicd/CicdTarget.java | SPI for target platforms |
src/main/java/com/pragmatik/buildtools/cicd/CicdService.java | @Service — MCP tool surface (2 tools) |
src/main/java/com/pragmatik/buildtools/cicd/GitHubActionsTarget.java | @Component — GitHub Actions YAML generator |
src/main/java/com/pragmatik/buildtools/cicd/PipelineShapeDetector.java | NL description → pipeline shape |
src/main/java/com/pragmatik/buildtools/cicd/CicdValidator.java | YAML syntax + required-field validation |
src/main/resources/cicd/templates/ci-push.yml | Push-only template |
src/main/resources/cicd/templates/ci-pr.yml | Pull-request template |
src/main/resources/cicd/templates/ci-release.yml | Release/deploy template |
src/main/resources/cicd/templates/ci-full.yml | Full pipeline template |
src/test/java/com/pragmatik/buildtools/cicd/CicdServiceTest.java | Integration tests |
src/test/java/com/pragmatik/buildtools/cicd/GitHubActionsTargetTest.java | YAML generation tests |
src/test/java/com/pragmatik/buildtools/cicd/PipelineShapeDetectorTest.java | Shape detection tests |
Files to Modify¶
| File | Change |
|---|---|
BuildToolsApplication.java | Register CicdService bean |
docs/reference/tools.md | Add interpret_ci_flow and validate_ci_config |
README.md | Mention CI/CD generation in features list |
9. Test Scenarios¶
Scenario 1: Basic push-triggered CI (Maven)¶
Tool: interpret_ci_flow
Input: description="Run tests on every push to main",
projectDir="/tmp/maven-project"
Expect: Detects Maven. Generates GitHub Actions YAML with:
- Trigger: push to main
- Job: Build (mvn verify -B)
- JDK matrix: ['21']
- Maven caching
- Validation: passes
Scenario 2: Full CI/CD pipeline (Gradle)¶
Tool: interpret_ci_flow
Input: description="Build on push to any branch, run tests on PR, deploy on release tag",
projectDir="/tmp/gradle-project"
Expect: Detects Gradle. Generates 3-job pipeline:
- Build: ./gradlew build (push to any branch)
- Test: ./gradlew test (PR trigger)
- Deploy: ./gradlew publish (tag trigger, needs test)
- Gradle wrapper caching enabled
- requiredSecrets includes DEPLOY_KEY
Scenario 3: SBT project with matrix¶
Tool: interpret_ci_flow
Input: description="Build and test on push",
projectDir="/tmp/sbt-project",
javaVersions="21,23"
Expect: Detects SBT. Generates:
- sbt test command
- Coursier cache
- JDK matrix: ['21', '23']
Scenario 4: Custom pipeline with config overrides¶
Tool: interpret_ci_flow
Input: description="Run tests weekly and on every push",
projectDir="/tmp/maven-project",
configOverrides='{"branches": ["main", "develop"],
"timeout": 45}'
Expect: Generates:
- Push trigger on main + develop
- Schedule trigger with cron expression
- 45-minute timeout on all jobs
Scenario 5: Explicit pipeline shape¶
Tool: interpret_ci_flow
Input: description="Release pipeline",
pipelineShape="ci-release",
projectDir="/tmp/maven-project"
Expect: Generates release pipeline with:
- Trigger: release published
- Build → Test → Deploy jobs
- Deploy conditioned on tag
Scenario 6: Validate existing CI config¶
Tool: validate_ci_config
Input: configContent="<valid yaml>", target="github-actions"
Expect: Validation passes. Returns {valid: true, warnings: []}
Scenario 7: Validate invalid CI config¶
Tool: validate_ci_config
Input: configContent="<yaml without name field>", target="github-actions"
Expect: Validation fails. Returns {valid: false,
errors: [{message: "Missing required field: name", line: 1}]}
Scenario 8: Unknown project type¶
Tool: interpret_ci_flow
Input: description="Build on push", projectDir="/tmp/python-project"
Expect: Returns error: "No JVM build tool detected.
Supported: Maven (pom.xml), Gradle (build.gradle/.kts), SBT (build.sbt)"
Scenario 9: Generated YAML write-friendly output¶
Tool: interpret_ci_flow(description="...", projectDir="...")
Expect: "suggestedPath": ".github/workflows/ci.yml" in output.
YAML content is valid per GitHub Actions schema.
Scenario 10: Multi-branch + multi-JDK¶
Tool: interpret_ci_flow
Input: description="Build on push to main, develop, and feature branches",
javaVersions="17,21,23",
projectDir="/tmp/gradle-project"
Expect: Generates:
- Trigger: push to main, develop, and ** (all branches)
- JDK matrix: ['17', '21', '23']
- Gradle caching with wrapper validation
10. Acceptance Criteria¶
- [ ]
interpret_ci_flowgenerates valid GitHub Actions YAML for Maven, Gradle, and SBT. - [ ] Pipeline shape detection correctly identifies
ci-push,ci-pr,ci-release,ci-full. - [ ] Build-tool-specific caching and JDK setup are correct per tool.
- [ ]
validate_ci_configdetects missing required fields and YAML syntax errors. - [ ] Generated YAML passes
actions/cachekey conventions for each build tool. - [ ] Output includes
suggestedPath,requiredSecrets, andpipelineSummary. - [ ] All 10 test scenarios pass.
- [ ] No dependency on external YAML rendering libraries (Java
String.format/SnakeYAMLare sufficient).