Add community bundle submission automation (#3553)

* Add community bundle submission automation

Add the discovery-only community bundle catalog, online and offline catalog loading, and a restricted agentic workflow for validating bundle submissions and opening draft catalog PRs.

Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: fbe794bc-667a-4c9e-b48b-825067debc6d

* Address community bundle review feedback

Ensure explicit install-allowed catalogs take precedence over built-in discovery, tighten component installability validation, and use issue-linked community branches.

Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: fbe794bc-667a-4c9e-b48b-825067debc6d

* Address follow-up bundle review feedback

Make offline catalog coverage content-agnostic and require autonomous catalog commits to include the assisted-by trailer.

Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: fbe794bc-667a-4c9e-b48b-825067debc6d

* Harden bundle catalog table rendering

Require single-line escaped Markdown table values for untrusted submission metadata. The needs-info label used by validation is now present in the repository.

Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: fbe794bc-667a-4c9e-b48b-825067debc6d

* Clear stale bundle validation labels

Allow the submission workflow to remove prior outcome labels before applying the current validation state.

Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: fbe794bc-667a-4c9e-b48b-825067debc6d
This commit is contained in:
Ben Buttigieg
2026-07-21 18:28:40 +01:00
committed by GitHub
parent 1f7290c975
commit 5760061316
14 changed files with 2222 additions and 12 deletions

View File

@@ -1,10 +1,30 @@
{
"entries": {
"actions/checkout@v6.0.3": {
"repo": "actions/checkout",
"version": "v6.0.3",
"sha": "df4cb1c069e1874edd31b4311f1884172cec0e10"
},
"actions/download-artifact@v8.0.1": {
"repo": "actions/download-artifact",
"version": "v8.0.1",
"sha": "3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c"
},
"actions/github-script@v9.0.0": {
"repo": "actions/github-script",
"version": "v9.0.0",
"sha": "3a2844b7e9c422d3c10d287c895573f7108da1b3"
},
"actions/setup-node@v6.4.0": {
"repo": "actions/setup-node",
"version": "v6.4.0",
"sha": "48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e"
},
"actions/upload-artifact@v7.0.1": {
"repo": "actions/upload-artifact",
"version": "v7.0.1",
"sha": "043fb46d1a93c77aae656e7c1c64a875d1fc6a0a"
},
"github/gh-aw-actions/setup@v0.79.8": {
"repo": "github/gh-aw-actions/setup",
"version": "v0.79.8",

1746
.github/workflows/add-community-bundle.lock.yml generated vendored Normal file

File diff suppressed because one or more lines are too long

View File

@@ -0,0 +1,288 @@
---
description: "Process community bundle submission issues - validate, add to catalog, and open a PR for maintainer review"
emoji: "📦"
on:
issues:
types: [labeled]
names: [bundle-submission]
skip-bots: [github-actions, copilot, dependabot]
tools:
edit:
bash: ["echo", "grep", "sort", "python3", "jq", "date"]
github:
toolsets: [issues, repos]
min-integrity: none
web-fetch:
permissions:
contents: read
issues: read
checkout:
fetch-depth: 0
safe-outputs:
noop:
report-as-issue: false
create-pull-request:
title-prefix: "[bundle] "
labels: [bundle-submission, automated]
draft: true
max: 1
allowed-files:
- bundles/catalog.community.json
- docs/community/bundles.md
protected-files:
policy: blocked
exclude:
- README.md
- CHANGELOG.md
add-comment:
max: 2
add-labels:
allowed: [bundle-submission, validation-passed, validation-failed, needs-info]
max: 3
remove-labels:
allowed: [validation-passed, validation-failed, needs-info]
---
# Add Community Bundle from Issue Submission
You are a catalog maintenance agent for the Spec Kit project. Process community
bundle submission issues and create draft pull requests that add or update
entries in the community bundle catalog.
Community bundles are untrusted. Validate metadata and distribution evidence,
but do not claim to audit, endorse, or support bundle code or the components it
installs. Never register a submitted companion catalog automatically.
## Triggering Conditions
This workflow is triggered by an `issues: labeled` event and is gated to the
`bundle-submission` label. Before processing, verify that the issue title starts
with `[Bundle]:`. If it does not, stop without commenting.
## Step 1 - Read and Parse the Issue
Read issue #${{ github.event.issue.number }} and extract these issue-form fields:
| Field | Issue Form ID | Required |
|-------|---------------|----------|
| Bundle ID | `bundle-id` | Yes |
| Bundle Name | `bundle-name` | Yes |
| Version | `version` | Yes |
| Role or Team | `role` | Yes |
| Description | `description` | Yes |
| Author | `author` | Yes |
| Repository URL | `repository` | Yes |
| Download URL | `download-url` | Yes |
| Documentation URL | `documentation` | Yes |
| License | `license` | Yes |
| Required Spec Kit Version | `speckit-version` | Yes |
| Integration Target | `integration` | No |
| Components Provided | `components-provided` | Yes |
| Required Component Catalogs | `required-catalogs` | Yes |
| Tags | `tags` | Yes |
| Key Features | `features` | Yes |
| Testing Details | `testing-details` | Yes |
| Example Usage | `example-usage` | Yes |
| Proposed Catalog Entry | `catalog-entry` | Yes |
Issue-form values appear beneath headings matching their labels.
## Step 2 - Validate the Submission
Run every check and collect all failures before deciding the outcome.
### 2a. Bundle ID and version
- The bundle ID must match
`^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$`.
- The version must be semantic version `X.Y.Z` with digits only and no `v`
prefix.
### 2b. Repository and documentation
- Restrict repository and documentation URLs to public GitHub URLs before
fetching them.
- Confirm the repository exists and contains `bundle.yml`, `README.md`, and a
license file (`LICENSE`, `LICENSE.md`, or `LICENSE.txt`).
- The documentation URL must resolve to a readable Markdown file that explains
the bundle's intended role, installed components, required catalogs, and
installation steps.
- Confirm the repository's `bundle.yml` matches the submitted bundle ID,
version, role, author, license, Spec Kit requirement, integration target, and
component summary.
### 2c. Release artifact
- The download URL must be an HTTPS GitHub release asset URL under the submitted
repository:
`https://github.com/<owner>/<repo>/releases/download/<tag>/<asset>.zip`.
- Confirm the release exists, its tag corresponds to the submitted version
(`vX.Y.Z` or `X.Y.Z`), and the exact ZIP asset is attached to that release.
- Confirm the asset name is versioned and consistent with the submitted bundle
ID and version.
Do not fetch arbitrary user-provided URLs. Do not claim the artifact was
executed or audited; rely on the required submission attestations for build and
installation evidence.
### 2d. Catalog entry
Parse the proposed JSON and require one entry under the submitted bundle ID.
Confirm that:
- `id`, `name`, `version`, `role`, `description`, `author`, `license`,
`download_url`, and `repository` match the submission and manifest.
- `requires.speckit_version` matches the submission.
- `provides` contains non-negative integer counts for `extensions`, `presets`,
`steps`, and `workflows`, matching the manifest.
- `tags` contains 2-5 lowercase strings and matches the submitted tags.
- `verified` is the boolean value `false`. Community entries must never be
marked verified.
### 2e. Component resolution
- `Required Component Catalogs` must explicitly say `None` or list every
non-default extension, preset, workflow, and step catalog needed by the
bundle.
- Compare the manifest references, README, required-catalog field, testing
details, and example usage for consistency.
- If non-default catalogs are required, ensure each URL is HTTPS, the README
documents the corresponding `catalog add` command, and the testing details
say those catalogs were registered in the clean-project test.
- If the field says `None` but a component is not bundled and cannot be
installed from a default Spec Kit catalog, fail validation and ask the
submitter to list and document an install-allowed companion catalog.
The community bundle catalog itself remains discovery-only. Companion catalog
URLs are documentation and validation metadata, not catalogs this workflow
should add to Spec Kit.
### 2f. Checklists and testing evidence
- Confirm every required checkbox in Testing Checklist and Submission
Requirements is checked (`[x]`).
- Confirm Testing Details describe validation, build, artifact installation,
and clean-project testing.
- Confirm Example Usage includes artifact installation and, when applicable,
all required catalog setup commands.
### Validation outcome
If any check fails:
1. Comment once with every failed check and a specific correction.
2. Remove `validation-passed`.
3. Add `validation-failed`; add `needs-info` when submitter input is needed.
4. Stop without editing files or creating a pull request.
If all checks pass, remove `validation-failed` and `needs-info`, add
`validation-passed`, and continue.
## Step 3 - Determine Add or Update
Search `bundles/catalog.community.json` for the bundle ID.
- If absent, add a new entry.
- If present, update the existing entry in place.
Treat a submitted version lower than or equal to the existing catalog version
as a validation failure unless the issue clearly documents a metadata-only
correction at the same version.
## Step 4 - Update the Community Catalog
Edit `bundles/catalog.community.json`. Insert new entries alphabetically by
bundle ID. The entry shape is:
```json
{
"<bundle-id>": {
"name": "<bundle-name>",
"id": "<bundle-id>",
"version": "<version>",
"role": "<role>",
"description": "<description>",
"author": "<author>",
"license": "<license>",
"download_url": "<download-url>",
"repository": "<repository>",
"requires": {
"speckit_version": "<speckit-version>"
},
"provides": {
"extensions": 0,
"presets": 0,
"steps": 0,
"workflows": 0
},
"tags": ["<tag>"],
"verified": false
}
}
```
Use the validated proposed entry rather than inventing metadata. Keep
`verified: false`. Update the top-level `updated_at` to today's UTC date at
midnight and preserve the top-level `catalog_url`.
Validate the complete file:
```bash
python3 -c "import json; json.load(open('bundles/catalog.community.json')); print('Valid JSON')"
```
## Step 5 - Update Community Documentation
Add or update the bundle in `docs/community/bundles.md`. Keep rows alphabetical
by bundle name:
```text
| <Name> | <Description> | `<role>` | <component counts> | <None or documented> | [<repo-name>](<repository>) |
```
Before rendering the row, convert every user-derived display value to
single-line plain text: collapse CR/LF sequences to spaces, remove control
characters, and backslash-escape `\`, `|`, backticks, `*`, `_`, `[`, `]`, `<`,
and `>`. Use the validated HTTPS GitHub repository URL unchanged only as the
Markdown link destination.
Render component counts compactly, omitting zero-valued component types. Use
`None` when no companion catalogs are needed and `Documented` otherwise; the
repository README remains the source for the actual URLs.
## Step 6 - Create a Draft Pull Request
Create one draft pull request.
- New entry branch:
`community/${{ github.event.issue.number }}-add-<bundle-id>-bundle`
- Update branch:
`community/${{ github.event.issue.number }}-update-<bundle-id>-bundle`
- New title: `Add <Bundle Name> bundle to community catalog`
- Update title: `Update <Bundle Name> bundle to v<version>`
The commit and PR description must summarize the catalog and documentation
changes, list the validation results, include
`Closes #${{ github.event.issue.number }}`, and mention the submitter with
`cc @<issue-author>`.
End the commit message with this authorship trailer:
```text
Assisted-by: GitHub Copilot (model: <name-if-known>, autonomous)
```
## Important Rules
- Modify only `bundles/catalog.community.json` and
`docs/community/bundles.md`.
- Keep JSON entries sorted by ID and documentation rows sorted by name.
- Never set a community bundle's `verified` field to true.
- Never add, enable, or change the policy of a submitted catalog.
- Never describe validation as a security audit or endorsement.
- Use `Closes`, not `Fixes`, for the submission issue.

View File

@@ -9,11 +9,13 @@ jobs:
if: >
(github.event.action == 'opened' && (
contains(github.event.issue.labels.*.name, 'extension-submission') ||
contains(github.event.issue.labels.*.name, 'preset-submission')
contains(github.event.issue.labels.*.name, 'preset-submission') ||
contains(github.event.issue.labels.*.name, 'bundle-submission')
)) ||
(github.event.action == 'labeled' && (
github.event.label.name == 'extension-submission' ||
github.event.label.name == 'preset-submission'
github.event.label.name == 'preset-submission' ||
github.event.label.name == 'bundle-submission'
))
runs-on: ubuntu-latest
permissions:

View File

@@ -0,0 +1,6 @@
{
"schema_version": "1.0",
"updated_at": "2026-07-15T00:00:00Z",
"catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/bundles/catalog.community.json",
"bundles": {}
}

View File

@@ -5,7 +5,10 @@
Bundles compose existing Spec Kit components — extensions, presets, workflows, and steps — into a single role or team stack. They are useful when a user should be able to install a tested set of components together instead of following several separate install commands.
Accepted community bundle entries will be listed here once a community bundle catalog is available. To submit a bundle for review, file a [Bundle Submission](https://github.com/github/spec-kit/issues/new?template=bundle_submission.yml) issue.
Accepted community bundle entries are published in [`bundles/catalog.community.json`](https://github.com/github/spec-kit/blob/main/bundles/catalog.community.json) and listed below. The built-in community source is discovery-only: `specify bundle search` and `specify bundle info` can inspect entries, but installing by ID requires explicitly adding an install-allowed catalog. Explicit catalogs use a higher default precedence than the built-in community source. To submit a bundle for review, file a [Bundle Submission](https://github.com/github/spec-kit/issues/new?template=bundle_submission.yml) issue.
| Bundle | Purpose | Role or team | Provides | Required catalogs | URL |
|--------|---------|--------------|----------|-------------------|-----|
## What to Submit

View File

@@ -48,6 +48,8 @@ packages = ["src/specify_cli"]
"workflows/speckit" = "specify_cli/core_pack/workflows/speckit"
# Bundled presets (installable via `specify preset add <name>` or `specify init --preset <name>`)
"presets/lean" = "specify_cli/core_pack/presets/lean"
# Community bundle catalog snapshot (used for offline discovery)
"bundles/catalog.community.json" = "specify_cli/core_pack/bundles/catalog.community.json"
[project.optional-dependencies]
test = [

View File

@@ -43,7 +43,7 @@ class Scope(str, Enum):
BUILTIN_DEFAULT_STACK: tuple[dict[str, Any], ...] = (
{"id": "default", "url": "builtin://default", "priority": 1,
"install_policy": InstallPolicy.INSTALL_ALLOWED.value},
{"id": "community", "url": "builtin://community", "priority": 2,
{"id": "community", "url": "builtin://community", "priority": 20,
"install_policy": InstallPolicy.DISCOVERY_ONLY.value},
)

View File

@@ -15,25 +15,26 @@ from pathlib import Path
from urllib.parse import ParseResult, urlparse
from urllib.request import url2pathname
from ..._assets import _locate_core_pack, _repo_root
from .. import BundlerError
from ..lib.yamlio import loads_json
from ..models.catalog import CatalogSource
from ..models.manifest import ComponentRef
# Built-in catalog payloads ship empty by default; a host distribution can
# replace these with curated content. Keeping them here makes ``search``/``info``
# work fully offline against the default stack.
COMMUNITY_CATALOG_URL = (
"https://raw.githubusercontent.com/github/spec-kit/main/"
"bundles/catalog.community.json"
)
# The default catalog is reserved for first-party bundles. The community
# catalog is loaded from the repository online and from the packaged snapshot
# offline so discovery remains useful without network access.
_BUILTIN_CATALOGS: dict[str, dict] = {
"builtin://default": {
"schema_version": "1.0",
"catalog_url": "builtin://default",
"bundles": {},
},
"builtin://community": {
"schema_version": "1.0",
"catalog_url": "builtin://community",
"bundles": {},
},
}
HTTP_TIMEOUT_SECONDS = 10
@@ -95,6 +96,18 @@ def _validate_remote_url(source_id: str, url: str) -> None:
)
def _load_packaged_community_catalog() -> dict:
core_pack = _locate_core_pack()
path = (
core_pack / "bundles" / "catalog.community.json"
if core_pack is not None
else _repo_root() / "bundles" / "catalog.community.json"
)
if not path.is_file():
raise BundlerError(f"Bundled community catalog not found: {path}")
return loads_json(path.read_text(encoding="utf-8"), origin=str(path))
def make_catalog_fetcher(*, allow_network: bool = True):
"""Return a fetcher callable suitable for :class:`CatalogStack`.
@@ -108,6 +121,10 @@ def make_catalog_fetcher(*, allow_network: bool = True):
scheme = parsed.scheme.lower()
if scheme == "builtin":
if url == "builtin://community":
if allow_network:
return _http_get_json(source.id, COMMUNITY_CATALOG_URL)
return _load_packaged_community_catalog()
payload = _BUILTIN_CATALOGS.get(url)
if payload is None:
raise BundlerError(f"Unknown built-in catalog '{url}'.")

View File

@@ -5,6 +5,8 @@ built-in, install policy gating, payload parsing.
"""
from __future__ import annotations
import json
import tomllib
from pathlib import Path
import yaml
@@ -37,6 +39,7 @@ def test_builtin_default_stack_when_no_config(tmp_path: Path):
assert ids == ["default", "community"]
assert sources[0].install_policy is InstallPolicy.INSTALL_ALLOWED
assert sources[1].install_policy is InstallPolicy.DISCOVERY_ONLY
assert sources[1].priority == 20
assert all(s.scope is Scope.BUILTIN for s in sources)
@@ -95,6 +98,29 @@ def test_builtin_default_stack_constant_shape():
assert ids == {"default", "community"}
def test_repository_community_bundle_catalog_matches_contract():
catalog_path = Path(__file__).parents[2] / "bundles" / "catalog.community.json"
payload = json.loads(catalog_path.read_text(encoding="utf-8"))
assert payload["schema_version"] == "1.0"
assert payload["catalog_url"].endswith("/bundles/catalog.community.json")
entries = load_catalog_payload(payload)
assert all(entry.verified is False for entry in entries.values())
def test_wheel_packages_community_bundle_catalog():
repo_root = Path(__file__).parents[2]
with (repo_root / "pyproject.toml").open("rb") as pyproject_file:
pyproject = tomllib.load(pyproject_file)
force_include = pyproject["tool"]["hatch"]["build"]["targets"]["wheel"][
"force-include"
]
assert force_include["bundles/catalog.community.json"] == (
"specify_cli/core_pack/bundles/catalog.community.json"
)
def test_catalog_entry_rejects_string_tags():
from specify_cli.bundler.models.catalog import CatalogEntry

View File

@@ -38,6 +38,27 @@ def test_resolve_prefers_highest_precedence_source():
assert resolved.install_allowed is False
def test_explicit_catalog_shadows_builtin_community_at_default_priority():
sources = [
_source("community", 20, "discovery-only"),
_source("explicit", 10, "install-allowed"),
]
payloads = {
"community": catalog_payload({
"shared": catalog_entry_dict("shared", version="1.0.0"),
}),
"explicit": catalog_payload({
"shared": catalog_entry_dict("shared", version="2.0.0"),
}),
}
resolved = _stack(sources, payloads).resolve("shared")
assert resolved.source.id == "explicit"
assert resolved.entry.version == "2.0.0"
assert resolved.install_allowed is True
def test_resolve_unknown_bundle_errors():
stack = _stack(
[_source("only", 1, "install-allowed")],

View File

@@ -31,6 +31,25 @@ def test_builtin_catalog_resolves_offline():
assert stack.search() == []
def test_builtin_community_catalog_resolves_from_packaged_snapshot_offline():
fetcher = make_catalog_fetcher(allow_network=False)
source = _src(
"community",
"builtin://community",
priority=20,
policy="discovery-only",
)
payload = fetcher(source)
stack = CatalogStack([source], fetcher)
assert isinstance(payload.get("bundles"), dict)
assert all(
result.source.id == "community" and not result.install_allowed
for result in stack.search()
)
assert stack.sources[0].install_allowed is False
def test_file_catalog_resolves_offline(tmp_path: Path):
catalog_path = tmp_path / "catalog.json"
write_catalog_file(catalog_path, {"demo": catalog_entry_dict("demo")})

View File

@@ -39,3 +39,21 @@ def test_pinned_action_ref_accepts_uppercase_hex_sha():
assert PINNED_SHA_RE.search(
"actions/example@0123456789ABCDEF0123456789ABCDEF01234567"
)
def test_community_bundle_submission_automation_is_wired():
source = WORKFLOWS_DIR / "add-community-bundle.md"
compiled = WORKFLOWS_DIR / "add-community-bundle.lock.yml"
assignment = WORKFLOWS_DIR / "catalog-assign.yml"
assert source.is_file()
assert compiled.is_file()
source_text = source.read_text(encoding="utf-8")
assignment_text = assignment.read_text(encoding="utf-8")
assert "names: [bundle-submission]" in source_text
assert "bundles/catalog.community.json" in source_text
assert "docs/community/bundles.md" in source_text
assert "verified: false" in source_text
assert "allowed-files:" in source_text
assert "bundle-submission" in assignment_text

View File

@@ -71,6 +71,48 @@ def test_http_fetch_rejects_non_https_final_url(monkeypatch):
fetcher(_source("https://example.com/c.json"))
def test_builtin_community_catalog_fetches_repository_catalog_online(monkeypatch):
captured: dict = {}
def fake_http_get_json(source_id, url):
captured["source_id"] = source_id
captured["url"] = url
return {"schema_version": "1.0", "bundles": {}}
monkeypatch.setattr(adapters, "_http_get_json", fake_http_get_json)
fetcher = adapters.make_catalog_fetcher(allow_network=True)
result = fetcher(_source("builtin://community"))
assert result["bundles"] == {}
assert captured == {
"source_id": "team",
"url": adapters.COMMUNITY_CATALOG_URL,
}
def test_builtin_community_catalog_uses_core_pack_snapshot_offline(
monkeypatch, tmp_path
):
catalog_path = tmp_path / "bundles" / "catalog.community.json"
catalog_path.parent.mkdir()
catalog_path.write_text(
'{"schema_version":"1.0","bundles":{"packaged":{'
'"id":"packaged","name":"Packaged","version":"1.0.0",'
'"role":"developer","description":"Packaged catalog entry.",'
'"author":"Spec Kit","license":"MIT","download_url":"",'
'"requires":{"speckit_version":">=0.1.0"},'
'"provides":{},"verified":false}}}',
encoding="utf-8",
)
monkeypatch.setattr(adapters, "_locate_core_pack", lambda: tmp_path)
fetcher = adapters.make_catalog_fetcher(allow_network=False)
result = fetcher(_source("builtin://community"))
assert "packaged" in result["bundles"]
@pytest.mark.parametrize(
"url",
[