Contribute a demo
Add a new automation orchestrator scenario to this marketplace. Fork the repo, turn on GitHub Pages so you can preview your card and detail page, then open a pull request when it looks right.
What you are contributing
Each demo is a top-level folder (playbooks, workflow JSON, docs) plus a few catalog files that make it show up on the GitHub Pages site. You do not need to be a maintainer to propose one - a clear PR with the minimum files below is enough to start a review.
Upstream repo: github.com/ansible-tmm/aap-orchestrator-demos
1. Fork and clone
- Open ansible-tmm/aap-orchestrator-demos and click Fork. Keep the repository name
aap-orchestrator-demosso the site URL path matches this project’sbaseurl. - Clone your fork locally:
git clone https://github.com/<your-username>/aap-orchestrator-demos.git - Create a branch for your work:
git checkout -b add-<demo-slug>-demo
2. Preview on GitHub Pages
The marketplace is a Jekyll site. The easiest way to see your new card and detail page is to enable Pages on your fork - same setup the upstream site uses.
- In your fork on GitHub, go to Settings → Pages.
- Under Build and deployment, set Source to Deploy from a branch.
- Set Branch to
main(or your working branch) and folder to / (root), then save. - Wait a minute for the deploy to finish (Actions → pages build, or a green check on the latest commit).
- Open your site at
https://<your-username>.github.io/aap-orchestrator-demos/
Tip: Push commits to the branch Pages is building from, refresh the site, and confirm the new demo card and detail page before you open the PR. If styles or links 404, double-check the repo is still named aap-orchestrator-demos (this site’s baseurl is /aap-orchestrator-demos).
3. Minimum requirements
Every new demo needs at least the following.
Demo folder
- Top-level directory named with a short kebab-case slug, e.g.
my-demo/. README.md- what the demo does, how to run it, and links to setup if needed.ao/*.json- importable automation orchestrator workflow export (required forstatus: active).- Playbooks under
playbooks/(oraap/playbooks/) that the workflow launches. - A setup doc when the environment is non-trivial (
SETUP_GUIDE.mdorREQUIREMENTS.md).
Marketplace wiring (required for the site)
_data/demos.yml- one catalog entry (slug,title,subtitle,category,status,blurb,url,github_path,github_doc). Setfeatured: falseunless a maintainer is swapping a featured slot._data/demo_pages.yml- detail copy:description,why_it_matters, andao_building_blockskeys that match the glossary._data/demo_playbooks.yml- playbook table for the detail page (name, path, short description, runs on).demos/<slug>/index.html- stub page:---
layout: demo-detail
demo_slug: <slug>
---
Status
active- runnable end-to-end: workflow JSON, playbooks, and a setup path someone else can follow.coming-soon- idea or partial work is fine on the catalog, but say clearly what is missing in the README and detail copy.
4. File checklist
| Item | Required? | Notes |
|---|---|---|
<slug>/ folder |
Yes | Playbooks, AO JSON, docs |
<slug>/README.md |
Yes | Point github_doc at this file |
<slug>/ao/*.json |
For active | Clean import (no leftover credential IDs) |
_data/demos.yml entry |
Yes | featured: false by default |
_data/demo_pages.yml entry |
Yes | Description + why it matters + building blocks |
_data/demo_playbooks.yml entry |
For active | Keep in sync with the README playbook table |
demos/<slug>/index.html |
Yes | Detail page stub |
| Setup / requirements doc | Recommended | Use setup_guide in demos.yml when it differs from the README |
| Thumbnail / Arcade / YouTube | Optional | Nice to have; not required for the first PR |
_config.yml exclude list |
Usually yes | Add <slug>/ next to the other demo folders so Jekyll does not publish playbook trees as site pages |
Use an existing active demo as a template - Disk Utilization is a good switch-routing example; RHEL CVE Remediation shows a fuller AI-oriented layout.
5. Open a pull request
- Commit your branch and push to your fork:
git push -u origin add-<demo-slug>-demo - On GitHub, open a pull request from your branch into
ansible-tmm/aap-orchestrator-demosmain. - In the PR description, include:
- What the demo shows (one or two sentences)
- Whether it is
activeorcoming-soon - Link to your GitHub Pages preview if you enabled it
- Any credentials, cloud accounts, or products a reviewer needs
- Expect review on catalog copy, workflow import cleanliness, and whether someone else can follow the setup docs.
House rules
- Featured cards: only three demos may have
featured: true. Do not add a fourth; ask a maintainer to swap. - Naming: in running text use automation orchestrator (not “Automation Orchestrator” title case). AO and AAP stay uppercase as acronyms.
- CTAs: primary GitHub button label is
View on GitHub(wired fromgithub_doc). - Secrets: never commit tokens, passwords, or real customer data. Workflow JSON should be safe to import.
Deeper technical notes live in DEVELOPER.md on GitHub.