mirror of
https://github.com/github/spec-kit.git
synced 2026-08-03 06:26:30 +08:00
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
1746
.github/workflows/add-community-bundle.lock.yml
generated
vendored
Normal file
1746
.github/workflows/add-community-bundle.lock.yml
generated
vendored
Normal file
File diff suppressed because one or more lines are too long
288
.github/workflows/add-community-bundle.md
vendored
Normal file
288
.github/workflows/add-community-bundle.md
vendored
Normal 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.
|
||||
6
.github/workflows/catalog-assign.yml
vendored
6
.github/workflows/catalog-assign.yml
vendored
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user