Quick Start: From Zero to Status Monitoring in 10 Minutes

This guide walks through adding status monitoring to an existing Docusaurus site. By the end, you'll have a /status page showing system health, powered by GitHub Issues and Actions.

Prerequisites

Before starting:

• Docusaurus site: Version 3.x, already deployed or running locally
• GitHub repository: The site's source code hosted on GitHub
• Node.js: Version 18+
• GitHub CLI (optional): For the label creation script (brew install gh or install guide)
• Repo permissions: GitHub Actions must have read/write access (Settings → Actions → General → Workflow permissions)

How It Works (30 seconds)

GitHub Actions (cron) → stentorosaur-monitor → JSON committed to status-data branch
                                                        ↓
                        Docusaurus build reads JSON → Static /status page

• Health checks run on a schedule via GitHub Actions
• Results are committed to a status-data branch (keeps main branch clean)
• Incidents are GitHub Issues with specific labels
• The plugin reads committed data at build time

Step 1: Install the Plugin

npm install @amiable-dev/docusaurus-plugin-stentorosaur

Step 2: Configure the Plugin

Add to your docusaurus.config.js:

module.exports = {
  plugins: [
    [
      '@amiable-dev/docusaurus-plugin-stentorosaur',
      {
        owner: 'your-github-org',
        repo: 'your-repo',
        token: process.env.GITHUB_TOKEN, // Optional: for private repos
        entities: [
          { name: 'api', type: 'system', displayName: 'API Service' },
          { name: 'website', type: 'system', displayName: 'Website' },
        ],
        // Optional: Enable runtime data fetching (v0.16+)
        dataSource: {
          strategy: 'github',
          owner: 'your-github-org',
          repo: 'your-repo',
        },
      },
    ],
  ],
};

Important: The name field must match exactly in the plugin config, .monitorrc.json, and GitHub labels. Case-sensitive.

Data Source Strategies (v0.16+)

The dataSource option enables runtime data fetching:

Strategy	Configuration	Use Case
github	{ strategy: 'github', owner, repo }	Public repos
http	{ strategy: 'http', url: '...' }	Private repos via proxy
static	{ strategy: 'static', path: '...' }	Bundled JSON files
build-only	{ strategy: 'build-only' }	No runtime fetch

For private repositories, use the http strategy with a server-side proxy that adds your GitHub token.

Step 3: Create the Status Data Branch

The monitoring workflow stores data on a separate status-data branch. Create it first:

# Create an orphan branch (no commit history from main)
git checkout --orphan status-data
git reset --hard
git commit --allow-empty -m "Initialize status-data branch"
git push origin status-data
git checkout main

This branch stores monitoring JSON files separately from your main codebase.

Step 4: Set Up Health Checks

Create .monitorrc.json in your repo root:

{
  "systems": [
    {
      "system": "api",
      "url": "https://api.yoursite.com/health",
      "method": "GET",
      "timeout": 10000,
      "expectedCodes": [200]
    },
    {
      "system": "website",
      "url": "https://yoursite.com",
      "method": "GET",
      "timeout": 10000,
      "expectedCodes": [200]
    }
  ]
}

The system field must match the name in your plugin config.

Step 5: Create the Monitoring Workflow

Create .github/workflows/monitor-systems.yml:

name: Monitor Systems
on:
  schedule:
    - cron: '0 * * * *'  # Every hour (adjust as needed)
  workflow_dispatch:      # Manual trigger for testing

permissions:
  contents: write
  issues: write

jobs:
  monitor:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout main (for config files)
        uses: actions/checkout@v4
        with:
          ref: main
          path: main

      - name: Checkout status-data branch
        uses: actions/checkout@v4
        with:
          ref: status-data
          path: status-data

      - name: Run health checks
        working-directory: main
        run: |
          npx -y -p @amiable-dev/docusaurus-plugin-stentorosaur stentorosaur-monitor \
            --config .monitorrc.json \
            --output-dir ../status-data \
            --verbose

      - name: Commit monitoring data
        working-directory: status-data
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          git diff --staged --quiet || git commit -m "Update monitoring data"
          git push origin status-data

Step 6: Create GitHub Labels

The plugin uses labels to identify status-related issues. Create these labels:

# Using GitHub CLI
gh label create status --color 0366d6 --description "Status tracking issue"
gh label create critical --color d73a4a --description "Complete outage"
gh label create major --color ff6f00 --description "Significant degradation"
gh label create minor --color fbca04 --description "Partial issues"
gh label create maintenance --color 8957e5 --description "Planned maintenance"
gh label create "system:api" --color 0e8a16 --description "API service"
gh label create "system:website" --color 0e8a16 --description "Website"

Or create them manually: Repo → Issues → Labels → New label.

Step 7: Verify the Setup

1. Trigger the workflow manually:

   • Go to Actions → Monitor Systems → Run workflow

2. Check the workflow logs:

   • Verify stentorosaur-monitor ran without errors
   • Check that it detected your endpoints

3. Verify data was committed:

   • Switch to the status-data branch
   • You should see current.json with health check results

4. View your status page locally:

   # Pull the status-data branch locally for the plugin to read
   git fetch origin status-data
   git worktree add status-data origin/status-data
   
   npm start

   Visit http://localhost:3000/status

Step 8: Test Incident Creation

Create a test incident to verify the full flow:

1. Go to your repo → Issues → New Issue
2. Title: API Service Down
3. Labels: status, critical, system:api
4. Body: Testing the status page
5. Submit the issue

Rebuild your site (npm run build) and check /status. The API Service should show as down with the incident details.

Close the issue to resolve the incident.

Troubleshooting

Error	Cause	Fix
fatal: couldn't find remote ref status-data	Branch doesn't exist	Run the branch creation commands from Step 3
Status page is empty	No monitoring data yet	Manually trigger the workflow and verify commits landed
Workflow 403 Forbidden	Insufficient permissions	Settings → Actions → Workflow permissions → Read and write
Workflow fails to push	Branch protection	Ensure status-data branch has no protection rules
Local status page doesn't show incidents	Data not pulled locally	Run git fetch origin status-data and ensure the worktree is set up

Optional: Add Notifications

Create .notifyrc.json for Slack alerts:

{
  "enabled": true,
  "channels": {
    "slack": {
      "enabled": true,
      "webhookUrl": "env:SLACK_WEBHOOK_URL"
    }
  }
}

Add to your workflow after the monitor step:

      - name: Send notifications
        if: always()
        continue-on-error: true
        working-directory: main
        run: |
          npx -y -p @amiable-dev/docusaurus-plugin-stentorosaur stentorosaur-notify \
            --config .notifyrc.json \
            --events ../status-data/events.json
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

Add SLACK_WEBHOOK_URL to repo secrets (Settings → Secrets → Actions).

Production Deployment

For the status page to update automatically, set up a deploy workflow that:

1. Checks out both main and status-data branches
2. Copies status data into the build directory
3. Deploys the built site

See the Architecture post for details on the data flow.

Summary

You now have:

• /status route showing system health
• Automated health checks via GitHub Actions
• Incident tracking via GitHub Issues
• Optional notifications to Slack/Discord/Email

Cost: $0 for public repos (GitHub Actions is free) Infrastructure: None (runs on GitHub's infrastructure) Maintenance: Minimal (update health check URLs as needed)

Next: Process Monitoring — tracking business workflows beyond infrastructure.