Submit Your Workshop

Orchestra’s catalog is git-managed — every workshop is a YAML file in the platform repository, reviewed like any other change. But you don’t have to write that YAML: fill in a structured issue form and a bot generates the file and opens the pull request for you (ADR-0009).

Fill in the form

1. Open a Workshop template issue from the repo’s issue templates and fill in the fields: display name, slug, image, app port, a compute size, tags, and — if your image needs them — environment variables and container args. (Making the image start unauthenticated on one port is the no-auth contract; the env/args help text points you at it.)

2. On submit, a bot validates your entry and comments. If a field is off, fix it by editing the issue description — validation re-runs on every edit (commenting doesn’t trigger it). When it’s valid, the comment invites a maintainer to approve.

3. A maintainer adds the approve label. A bot opens a pull request containing the generated YAML — reusing an existing slug updates that template (the diff shows the change); a new slug adds one. Your GitHub handle is recorded on the template as submittedBy automatically — it’s stamped from the issue author, not a field you fill in.

4. The PR is reviewed and merged like any other. Your workshop appears in the catalog on the next deploy, and merging closes your issue.

Tip

Comfortable with YAML? You can still add or edit a template file directly under the templates directory and open a PR yourself (see Authoring Workshop Templates) — the form is a convenience, not the only door.

Maintainers: driving the conversion by hand

When the GitHub App isn’t configured (or a maintainer wants to steer the PR locally), just template-from-issue <n> does what the convert Action does under your own gh auth: it parses issue <n>’s form, renders and validates the YAML, writes the file, branches, and opens the PR — stamping submittedBy from the issue author.

Who reviews it

The other side of the front door is a small group of platform admins. They’re the CODEOWNERS on the templates directory, so every template PR — hand-written or opened for you by the submission bot — requires their review, and branch protection makes “merged” mean “reviewed” (ADR-0009).

Admins also own the closed vocabularies the form offers: the size dropdown bundles a compute tier and a cpu/memory/storage profile that maps to what the cluster’s node pools can actually schedule. The workshop-specific fields (image, port, env, args) are yours; the capacity knobs are theirs. Need something outside a preset? Say so in the PR — an admin can adjust the generated YAML before merging.

Why a pull request

Keeping the catalog in git means every change is reviewed, attributed, and reversible — the same guarantees the rest of the platform gets. “Merged” always means “reviewed.”

Updating or retiring a workshop

Slugs are unique across the catalog — two templates can never share one. But resubmitting an existing slug isn’t an error: it’s how you update.

• Update — open a new issue form with the same slug (the generated PR shows the diff against the existing file), or edit the file and open another PR yourself.
• Retire — set the template inactive (or an admin removes the file). Retiring is an admin action.