Add operational workflow model for live-config repos - #287
Merged
Conversation
Introduce a second, first-class branching/workflow model alongside the default release model, selected per repo by a new registry `workflowModel` field (release | operational; default release). Operational repos (live-service config: Vantage-Config, ESPHome-Config, HomeAutomation, HomeAssistant-Config) commit configuration directly to `develop` (no feature branch) and promote a known-good snapshot to `main` via an occasional PR. Only the `develop` ruleset differs: a new repo-config/operational/develop.json allows direct signed pushes (deletion + non_fast_forward + required_signatures only), while main.json is shared - so the promotion PR still enforces the required lint check and a broken config can never reach `main`. develop = live edits with advisory CI on push; main = known-good snapshot with CI enforced on the promotion. CI for operational repos is lint/validation only (editorconfig/EOL plus domain linters - Home Assistant or ESPHome config validation, a firmware build - no unit tests). They still cut GitHub releases, but only by manual workflow_dispatch (releaseTrigger: dispatch-only), never automatically. Changes: - registry: workflowModel enum + property + default; mark the four operational repos (workflowModel, groundTruthBranch, dispatch-only release, github-release publish); validate.py enforces the enum. - repo-config: operational/develop.json variant; configure.sh selects the develop ruleset from the repo's workflowModel (override via 2nd arg). - spec/project-types.json: branch-model audit is model-aware; add the operational lint-CI expectation. - docs: AGENTS.md, WORKFLOW.md, repo-config/README.md, README.md document both models; cspell allows esphome/hass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a second, first-class workflow model (operational) to the fleet governance so “live config” repositories can commit directly to develop (advisory CI) while still gating develop -> main promotions via the shared main ruleset and required PR check, with publishing restricted to manual dispatch-only releases.
Changes:
- Introduce and document the
workflowModelregistry field (releasedefault,operationalnew) and mark the initial operational repos accordingly. - Add an operational
developruleset payload and teachrepo-config/configure.shto select thedevelopruleset by workflow model. - Make the audit/spec docs model-aware and extend spelling allowlist for operational-domain terms.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| WORKFLOW.md | Documents the new operational workflow model and how it maps onto existing guarantees/scenarios. |
| spec/validate.py | Adds validation for per-repo workflowModel values (and should also validate the defaults). |
| spec/project-types.json | Updates branch-model audit assertions to be workflow-model-aware and adds an operational lint-CI intent check. |
| repo-config/README.md | Documents the model-specific develop ruleset and updated configure.sh usage. |
| repo-config/operational/develop.json | Adds the operational develop ruleset payload for direct signed pushes. |
| repo-config/configure.sh | Selects the develop ruleset based on the repo’s workflowModel (or an override argument). |
| registry/repos.schema.json | Extends the registry schema to include workflowModel. |
| registry/repos.json | Adds defaults.workflowModel and marks specific repos as operational + dispatch-only release + GitHub release publish. |
| README.md | Updates “How This Repo Operates” branching summary to mention both workflow models. |
| cspell.json | Adds esphome and hass to the word list. |
| AGENTS.md | Documents the operational model in Branching Model / Release Model governance text. |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
…igure.sh fallback - spec/validate.py: validate repos.json defaults.workflowModel (configure.sh falls back to it, so an invalid default would break the apply while every per-repo entry still validated OK). - repo-config/configure.sh: add an explicit shell default so $model is never empty even if the jq lookup fails; document the fallback chain. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
WORKFLOW.md:287
- This section still uses an inline Markdown link and WORKFLOW.md currently lacks reference definitions for the new links. To follow the repo's reference-style-link convention (AGENTS.md "Documentation Style Conventions"), switch the inline link to a reference label and add link definitions under the existing "" block (also enabling the earlier Branch Model section to reference repo-config/README.md consistently).
- **Operational (workflow model, not a build target).** A `workflowModel: operational` repo layers a direct-commit `develop` onto the **source-only** release shape (above). Two workflows: (1) a **lint/validation** PR workflow feeding the required `Check pull request workflow status job` - the generic linters (editorconfig/EOL, markdownlint, cspell, actionlint) plus a domain validator (Home Assistant `hass --script check_config`, `esphome config`, a firmware build), **no unit tests**; its triggers differ from the `release` template - `push` to `develop` (advisory feedback on direct commits) plus `pull_request` to `main` (the enforced promotion gate) plus `workflow_dispatch`. (2) the standard **source-only publisher** on `workflow_dispatch` only (`releaseTrigger: dispatch-only`): NBGV + `version.json` own the tag, and a manual dispatch cuts a GitHub release (tag + source zip + README + LICENSE, `expect_release_assets: false`). Applicable scenarios: S1 (validation) on the promotion PR, plus the source-only release set - S7 (tag-only release), S8 (dispatch guard), S9 (no-op republish), S10 (classification). N/A: the auto-publish paths (S5/S6 bot-push and schedule - operational repos have neither) and every build/registry scenario. See the branch-model note in Section 3 and [AGENTS.md "Branching Model"](./AGENTS.md#branching-model).
<!-- Workflow -->
[workflows]: ./.github/workflows/
<!-- Repo -->
[codestyle]: ./CODESTYLE.md
Uh oh!
There was an error while loading. Please reload this page.
Convert the operational-model inline links to reference-style per AGENTS.md "Documentation Style Conventions" (WORKFLOW.md is not an agent-instruction file); add agents-branching-model and repo-config-readme definitions under the Repo group, alphabetized. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
…e.sh Distinguish a repo simply absent from the registry (jq falls back through defaults.workflowModel to release, exit 0) from a genuine jq/parse failure on a malformed registry (now exits 1 instead of silently applying the release ruleset). A missing registry file still defaults to release, with a warning; an explicit arg 2 always wins. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Comment on lines
214
to
220
| "name": "HomeAssistant-Config", | ||
| "url": "https://github.com/ptr727/HomeAssistant-Config", | ||
| "status": "cataloged", | ||
| "types": ["source-only"], | ||
| "groundTruthBranch": "master", | ||
| "groundTruthBranch": "main", | ||
| "workflowModel": "operational", | ||
| "hasDevelop": true, |
ptr727 added a commit
that referenced
this pull request
Jul 13, 2026
…epos (#292) Promote the current `develop` snapshot to `main`. Adds the **operational** workflow model and its supporting rules/tooling (PRs #287-#291): - **#287** operational `workflowModel` (direct-to-`develop` live-config repos; shared `main` ruleset; dispatch-only releases; model-aware `configure.sh`). - **#288** per-repo `lineEndings` field (operational repos follow the consuming app's platform; validated). - **#289** mixed-consumer EOL guidance (prefer splitting by platform); dropped the standalone Vantage-Config catalog entry (later re-added, recreated single-platform). - **#290** renamed `HomeAutomation` -> `HomeAutomation-Config`; EOL guidance leads with the split-preferred approach. - **#291** CODESTYLE.md defers line-ending governance to AGENTS.md (was hardcoding CRLF, contradicting `lf` operational repos). Applied end-to-end to ESPHome-Config, HomeAutomation-Config, HomeAssistant-Config (lf) and the recreated Vantage-Config (crlf). 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduces a second, first-class branching/workflow model - operational - alongside the default release model, selected per repo by a new registry
workflowModelfield (release|operational, defaultrelease).Operational repos (live-service config: Vantage-Config, ESPHome-Config, HomeAutomation, HomeAssistant-Config) commit configuration directly to
develop(no feature branch) and promote a known-good snapshot tomainvia an occasional PR.developruleset differs: newrepo-config/operational/develop.jsonallows direct signed pushes (deletion+non_fast_forward+required_signaturesonly).main.jsonis shared, so the promotion PR still enforces the required lint check - a broken config can never reachmain.develop= live edits with advisory CI on push;main= known-good snapshot with CI enforced on the promotion.workflow_dispatch(releaseTrigger: dispatch-only), never automatically.Changes
workflowModelenum + property + default; four operational repos marked (workflowModel,groundTruthBranch,dispatch-onlyrelease,github-releasepublish);validate.pyenforces the enum.operational/develop.jsonvariant;configure.shselects thedevelopruleset from the repo'sworkflowModel(override via 2nd arg).esphome/hass.Verification
python3 spec/validate.pypasses (21 cataloged clean; rejects an invalidworkflowModel);bash -n configure.shclean;configure.shmodel resolution verified for all repos; markdownlint + cspell + editorconfig-checker green.Follow-up (separate, per-repo rollout)
Bringing the four repos up to the operational baseline (missing files, lint+domain CI,
version.json+publish-release.yml, apply rulesets) is a separate live-repo effort, starting with ESPHome-Config end-to-end.🤖 Generated with Claude Code