Skip to main content

Introducing Stentorosaur: Status Monitoring Meets Documentation

· 5 min read
Chris
Chris
Amiable Dev
Claude
Claude
AI Assistant

The Problem: Status Page Infrastructure Sprawl​

If you run a SaaS product or developer platform, you need a status page. The standard approach? Subscribe to Statuspage.io ($29-$99/month), spin up a separate domain, configure separate auth, and maintain another deployment pipeline—all to tell users when your actual service is down.

That's a lot of infrastructure to maintain just to communicate outages.

For teams already using Docusaurus for documentation, this creates additional friction:

  • Separate hosting: Another domain to configure and renew
  • Separate deployments: Another CI/CD pipeline to maintain
  • Fragmented UX: Users bounce between docs and status page
  • Duplicate theming: Keep two sites visually consistent

The Solution: Status Monitoring Inside Docusaurus​

Stentorosaur is a Docusaurus plugin built on Upptime's architecture. It uses GitHub Issues for incident tracking and GitHub Actions for automated health checks—no servers, no databases, no separate subscriptions.

Install the plugin:

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

Configure your endpoints in docusaurus.config.js:

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

New in v0.16: The dataSource option enables runtime data fetching with four strategies: github (public repos), http (custom APIs/proxies), static (local files), and build-only (no runtime fetch). Private repository users can use the http strategy with a server-side proxy. See ADR-001 for details.

Define health check endpoints in .monitorrc.json:

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

Your docs site now has a /status route showing:

  • System health from automated polling (configurable intervals, typically 5-60 minutes)
  • Active incidents pulled from GitHub Issues
  • Scheduled maintenance windows
  • Historical uptime metrics and response time charts

How It Works​

GitHub Actions runs your health checks on a cron schedule. Results are committed as JSON to your repository. When a check fails, the workflow automatically opens a GitHub Issue with labels like status, critical, and system:api. When the system recovers, the issue is auto-closed with a recovery comment.

The Docusaurus plugin reads this committed data at build time and renders the status page. No runtime API calls to GitHub during page loads—just static data generated during your normal build process.

Data flow:

GitHub Actions (cron) → Health checks → JSON committed to repo
                                              ↓
                        Docusaurus build → Static status page

Trade-offs and Limitations​

Be aware of the constraints:

  • Monitoring frequency: GitHub Actions cron jobs run at minimum 5-minute intervals. This isn't sub-second monitoring.
  • GitHub API rate limits: 5,000 requests/hour with authentication. The plugin commits data to avoid hitting limits during builds.
  • Action minutes: Public repos get unlimited minutes; private repos use your Actions quota.
  • Build latency: Status updates appear after your next site build/deploy, not instantly.

For teams needing sub-minute alerting or complex escalation policies, this isn't a replacement for PagerDuty or Datadog. It's for teams who want a status page without the operational overhead.

Why It Matters​

1. Zero Additional Infrastructure No servers. No databases. No separate SaaS subscription. Your status page deploys with your docs.

2. GitHub-Native Workflow Incidents are GitHub Issues—your team already knows how to create, assign, and close them. Use labels for severity (critical, major, minor) and systems (system:api, system:database).

3. Beyond System Uptime Track business processes alongside infrastructure. Label an issue as process:checkout when the checkout flow breaks, even if all servers are "up." Your status page shows what users actually care about: "Can I complete my task?"

4. Automated Notifications Configure Slack, Telegram, Email, or Discord alerts. When health checks fail or issues open, your team knows.

Who Should Use It?​

  • Docusaurus users: If your docs are already on Docusaurus, adding status monitoring is trivial
  • Small teams: No budget for Statuspage? Use GitHub (free for public repos)
  • Open source projects: Public incident tracking via GitHub Issues
  • Internal tools teams: Monitor processes and SLAs, not just servers

What's Next?​

Upcoming posts cover:

GitHub Repository | npm Package

Acknowledgments​

Stentorosaur builds on Upptime by Anand Chowdhary. Upptime pioneered the GitHub-native, infrastructure-free approach to status monitoring. We've ported those concepts to work inside Docusaurus. If you want a standalone status page (not embedded in docs), use Upptime directly.