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

  1. Open ansible-tmm/aap-orchestrator-demos and click Fork. Keep the repository name aap-orchestrator-demos so the site URL path matches this project’s baseurl.
  2. Clone your fork locally:
    git clone https://github.com/<your-username>/aap-orchestrator-demos.git
  3. 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.

  1. In your fork on GitHub, go to Settings → Pages.
  2. Under Build and deployment, set Source to Deploy from a branch.
  3. Set Branch to main (or your working branch) and folder to / (root), then save.
  4. Wait a minute for the deploy to finish (Actions → pages build, or a green check on the latest commit).
  5. 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 for status: active).
  • Playbooks under playbooks/ (or aap/playbooks/) that the workflow launches.
  • A setup doc when the environment is non-trivial (SETUP_GUIDE.md or REQUIREMENTS.md).

Marketplace wiring (required for the site)

  • _data/demos.yml - one catalog entry (slug, title, subtitle, category, status, blurb, url, github_path, github_doc). Set featured: false unless a maintainer is swapping a featured slot.
  • _data/demo_pages.yml - detail copy: description, why_it_matters, and ao_building_blocks keys 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

  1. Commit your branch and push to your fork:
    git push -u origin add-<demo-slug>-demo
  2. On GitHub, open a pull request from your branch into ansible-tmm/aap-orchestrator-demos main.
  3. In the PR description, include:
    • What the demo shows (one or two sentences)
    • Whether it is active or coming-soon
    • Link to your GitHub Pages preview if you enabled it
    • Any credentials, cloud accounts, or products a reviewer needs
  4. 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 from github_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.