Add GitHub Actions Step: Auto-create Issue When API Docs Build Fails

[mildronize]

Enhance the CI workflow in kubricate-docs to automatically create a GitHub Issue when the API documentation generation (pnpm typedoc) fails. This will help detect silent documentation build failures and allow follow-up without blocking the rest of the deployment pipeline.

This feature will ensure robustness in documentation maintenance without interrupting mainline CI/CD flows.

🎯 Goal

• Automatically detect when typedoc fails
• Open a GitHub Issue in the same repo with useful context
• Allow the pipeline to continue by using continue-on-error
• Avoid duplicated issues for the same commit if possible

🧱 Design Guideline

• Use continue-on-error: true on the Generate API Docs step.
• Capture the failure using a conditional exit_code check via GITHUB_OUTPUT.
• Add a new step that uses [JasonEtco/create-an-issue](https://github.com/marketplace/actions/create-an-issue) to generate a GitHub Issue from a Markdown template.
• Add an Issue Template file at .github/ISSUE_TEMPLATE/typedoc-failure.md.
• Configure the workflow permissions to include issues: write.

📂 File Changes

1. .github/workflows/docs.yml

   • Modify typedoc step to set exit_code on failure
   • Add step to trigger create-an-issue if exit_code is present
   • Add permissions: issues: write block

2. .github/ISSUE_TEMPLATE/typedoc-failure.md

   • Provide structured context (commit SHA, docs path, workflow link)

✅ Implementation Checklist

• Update the CI workflow to include error-tolerant doc generation
• Detect doc generation failure via exit code
• Configure create-an-issue GitHub Action
• Add a markdown template for typedoc failures
• Grant issues: write permission to the workflow

🧪 Test Plan

• Manually break the typedoc step (e.g. with invalid syntax)

• Push to main and observe that:

  • CI continues
  • A GitHub Issue is automatically created with correct context

• Validate behavior on repeated failures (should avoid duplicates or include commit reference)

แน่นอนครับ ✨ ด้านล่างคือ Implementation Code Section ที่มายสามารถ copy ไปใช้ได้ทันทีตาม Checklist:

---

🧩 Code Section for Implementation Plan

✅ 1. Generate API Docs step (with error tolerance and exit code)

      - name: Generate API Docs
        id: generate_docs
        run: |
          pnpm typedoc || echo "exit_code=$?" >> "$GITHUB_OUTPUT"
        working-directory: ${{ env.DOCS_PATH }}
        continue-on-error: true

---

✅ 2. Create Issue if typedoc fails

      - name: Open Issue if Typedoc Failed
        if: steps.generate_docs.outputs.exit_code != ''
        uses: JasonEtco/create-an-issue@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          filename: .github/ISSUE_TEMPLATE/typedoc-failure.md

---

✅ 3. Set permissions in workflow (top-level)

permissions:
  contents: read
  issues: write

---

✅ 4. Create Issue Template at .github/ISSUE_TEMPLATE/typedoc-failure.md

---
title: "🚨 API Docs Generation Failed"
labels: bug, docs
assignees: your-github-username
---

## ❌ Typedoc generation failed

The `pnpm typedoc` command failed during a CI run.

### 🔍 Context

- **Commit**: `${{ github.sha }}`
- **Docs Path**: `${{ env.DOCS_PATH }}`
- **Workflow Run**: [See run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})

### 🛠 Suggested Actions

- Investigate the error logs in the `Generate API Docs` step
- Test the typedoc generation locally
- Fix or patch the issue and verify with a clean CI run