[FEAT] Auto-generate showcase example branches from templates via CI

[colbytimm]

Summary

Create a GitHub Actions workflow that generates example projects from each template variant (language × cloud_service) and pushes them to dedicated branches in a separate showcase repository. This gives users real, browsable code examples for every supported combination without maintaining them manually. The workflow triggers whenever a template changes in the main repo, keeping examples in sync automatically.

Category: ci, documentation

Acceptance Criteria

• New GitHub Actions workflow in cookiecutter-api (e.g., .github/workflows/generate-examples.yaml)
• Triggers on push to main when files under python/, typescript/, dotnet/, or go/ change
• For each language × cloud_service combination, the workflow:
  • Generates a project using cookiecutter --no-input with sensible defaults
  • Pushes the generated output to a branch in the showcase repo
  • Each branch contains only the generated project files (not the template)
• Showcase repo has a main branch with a README.md that:
  • Links to each example branch
  • Includes the same support matrix table from the template repo
  • Explains that branches are auto-generated and should not be edited directly
• Workflow uses a GitHub App token or deploy key with push access to the showcase repo
• Branch names follow a consistent pattern: {language}-{cloud} (e.g., python-azure, typescript-gcp, dotnet-aws)
• New branches are automatically added when new cloud_service options appear in a template's cookiecutter.json
• Repo name is TBD (owner will create the repo; workflow references it via a repository variable or secret)

Implementation Notes

Workflow Structure

name: Generate Examples

on:
  push:
    branches: [main]
    paths:
      - 'python/**'
      - 'typescript/**'
      - 'dotnet/**'
      - 'go/**'

jobs:
  generate:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - language: python
            cloud: "Azure Function App"
            branch: python-azure
          - language: python
            cloud: "GCP Cloud Function"
            branch: python-gcp
          - language: typescript
            cloud: "Azure Function App"
            branch: typescript-azure
          - language: typescript
            cloud: "GCP Cloud Function"
            branch: typescript-gcp
          - language: dotnet
            cloud: "Azure Function App"
            branch: dotnet-azure
          - language: go
            cloud: "Azure Function App"
            branch: go-azure
    steps:
      - uses: actions/checkout@v4
      - name: Install Cookiecutter
        run: pip install cookiecutter jinja2-strcase
      - name: Generate Project
        run: |
          cookiecutter ./${{ matrix.language }} --no-input \
            project_name="ExampleApi" \
            cloud_service="${{ matrix.cloud }}"
      - name: Push to showcase repo
        run: |
          # Clone showcase repo, checkout orphan branch, copy files, push

Authentication

• Use a GitHub App or deploy key (not a PAT) for pushing to the showcase repo
• Store credentials as repository secrets

Showcase Repo README

The main branch README links to each branch:

## Examples

| Language | Azure | AWS | GCP |
|----------|-------|-----|-----|
| Python | [python-azure](../../tree/python-azure) | — | [python-gcp](../../tree/python-gcp) |
| TypeScript | [typescript-azure](../../tree/typescript-azure) | — | [typescript-gcp](../../tree/typescript-gcp) |
| ... | ... | ... | ... |

Dynamic Matrix (Future Enhancement)

Instead of hardcoding the matrix, the workflow could parse each cookiecutter.json to dynamically build the matrix of language × cloud combinations. This ensures new cloud options are picked up automatically.