From 06d969f4cb93c09ca563caa720b3111b4adac685 Mon Sep 17 00:00:00 2001 From: Jon Langevin Date: Sat, 30 May 2026 19:09:04 -0400 Subject: [PATCH] docs: README + example for v0.2.0 (cigen smart GHA/GitLab, from_plan/phase_config, minEngineVersion 0.67.0) - Document config-derived GHA/GitLab via cigen (jenkins/circleci stay template) - Add step config field table incl from_plan/phase_config - Bump install version v0.1.3 -> v0.2.0; note workflow/wfctl >= v0.67.0 requirement - Fix minimal example: canonical platform github_actions + infra_config + http.server entry point so 'wfctl validate' passes (verified) Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 42 ++++++++++++++++++++++++++++-------- examples/minimal/config.yaml | 16 ++++++++++++-- 2 files changed, 47 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 966f9e7..6a730b1 100644 --- a/README.md +++ b/README.md @@ -5,12 +5,18 @@ [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Go Reference](https://pkg.go.dev/badge/github.com/GoCodeAlone/workflow-plugin-ci-generator.svg)](https://pkg.go.dev/github.com/GoCodeAlone/workflow-plugin-ci-generator) -CI/CD config generator for workflow projects — emits GitHub Actions, GitLab CI, Jenkins, and CircleCI pipelines from workflow project manifests. +CI/CD config generator for workflow projects — emits GitHub Actions, GitLab CI, Jenkins, and CircleCI pipelines from a workflow app config. + +As of **v0.2.0** the **GitHub Actions** and **GitLab CI** platforms are generated by the workflow engine's config-derived `cigen` engine (analyze → CIPlan → render): the output is *derived from your app config* — its required secrets, deploy phases, migrations, health-check smoke, and plugin-install needs — not a fixed template. **Jenkins** and **CircleCI** still use template generators (smart generation for those is future work). This is the same engine behind `wfctl ci plan` / `wfctl ci generate`. ## What it provides **Pipeline step types:** -- `step.ci_generate` — Generate CI/CD configuration files (GitHub Actions, GitLab CI, Jenkins, CircleCI) from a workflow project manifest +- `step.ci_generate` — Generate CI/CD configuration files from a workflow app config. GitHub Actions / GitLab CI are config-derived via `cigen`; Jenkins / CircleCI are template-based. + +## Requirements + +- Workflow engine / wfctl **≥ v0.67.0** (`minEngineVersion: 0.67.0`) — the release that exports the `cigen` package this plugin imports. ## Install @@ -19,7 +25,7 @@ CI/CD config generator for workflow projects — emits GitHub Actions, GitLab CI version: 1 plugins: - name: workflow-plugin-ci-generator - version: v0.1.3 + version: v0.2.0 source: github.com/GoCodeAlone/workflow-plugin-ci-generator ``` @@ -29,22 +35,40 @@ Then: wfctl plugin install ``` +## Step config + +`step.ci_generate` config / input fields: + +| Field | Purpose | +|-------|---------| +| `platform` | `github_actions` \| `gitlab_ci` \| `jenkins` \| `circleci` | +| `infra_config` | Path to the workflow app config to analyze (GHA/GitLab) | +| `output_dir` | Where to write the generated file(s) | +| `project_name` | Project label used in generated jobs | +| `runner` | Runner label (GitHub Actions) | +| `default_branch` | Default branch (default `main`) | +| `from_plan` | *(v0.2.0)* Path to a `CIPlan` JSON to render directly, skipping analysis — lets an AI/automation produce the plan via `wfctl ci plan`, edit it, then render it deterministically | +| `phase_config` | *(v0.2.0)* Path to a prerequisite-phase config (e.g. `deploy.prereq.yaml`) → emits a two-phase `apply-prereq` → `apply-deploy` pipeline | + +For GHA/GitLab the generated workflow wires each config-referenced secret as `${{ secrets.NAME }}`, includes a `wfctl plugin install` step when the app uses plugins, a `wfctl migrations up` step when `ci.migrations` is present, a plan-guard that fails on replace/destroy, and a health-check smoke job. Secret names the generator can't fully derive (e.g. IaC-output-backed or non-`UPPER_SNAKE` names) are surfaced as warnings on the `CIPlan` rather than silently guessed. + ## Minimal example See [`examples/minimal/config.yaml`](examples/minimal/config.yaml). ## Supported CI platforms -| Platform | Output file | -|----------|-------------| -| GitHub Actions | `.github/workflows/workflow.yml` | -| GitLab CI | `.gitlab-ci.yml` | -| Jenkins | `Jenkinsfile` | -| CircleCI | `.circleci/config.yml` | +| Platform | Output file | Generation | +|----------|-------------|------------| +| GitHub Actions | `.github/workflows/.yml` | config-derived (`cigen`) | +| GitLab CI | `.gitlab-ci.yml` | config-derived (`cigen`) | +| Jenkins | `Jenkinsfile` | template | +| CircleCI | `.circleci/config.yml` | template | ## Documentation - [Plugin authoring guide (upstream)](https://github.com/GoCodeAlone/workflow/blob/main/docs/PLUGIN_AUTHORING.md) +- [wfctl CLI reference — `ci plan` / `ci generate`](https://github.com/GoCodeAlone/workflow/blob/main/docs/WFCTL.md) - [Workflow engine docs](https://github.com/GoCodeAlone/workflow) ## License diff --git a/examples/minimal/config.yaml b/examples/minimal/config.yaml index 44a1ce5..f5be456 100644 --- a/examples/minimal/config.yaml +++ b/examples/minimal/config.yaml @@ -1,7 +1,18 @@ # workflow-plugin-ci-generator minimal example -# Generates CI/CD config files from a workflow project manifest. +# Exposes an HTTP endpoint that generates CI/CD config via step.ci_generate. +# GitHub Actions / GitLab CI are config-derived (cigen); Jenkins / CircleCI are template-based. # Validate with: wfctl validate --skip-unknown-types examples/minimal/config.yaml +modules: + - name: server + type: http.server + config: + address: ":8080" + + - name: router + type: http.router + dependsOn: [server] + workflows: pipeline: trigger: @@ -13,6 +24,7 @@ workflows: - name: generate-ci type: step.ci_generate config: - platform: github-actions + platform: github_actions + infra_config: app.yaml # the workflow app config cigen analyzes (GHA/GitLab) output_dir: . project_name: my-workflow-project