GitHub Runner & Workflow Monitor

Bash script that monitors GitHub self-hosted runner status and GitHub Actions workflows across multiple repositories. Sends alerts to a ClickUp chat channel when issues are detected.

---

Features

• Runner status monitoring: Detects when a self-hosted runner goes offline or comes back online
• Queued workflow detection: Finds workflows stuck in queue across all configured repos
• Failed workflow detection: Identifies recent failures within a configurable time window
• State-aware notifications: Only notifies on state transitions (avoids spam)
• API error handling: Validates HTTP status codes and response structure, notifies on auth/API failures
• Debug mode: Pass --debug for verbose output

---

Project Structure

scripts/
  check.sh          # Main script
  .env.example       # Environment variables template
  .gitignore         # Ignores .env and state file

---

Setup

1. Clone the repository

git clone https://github.com/your-org/github-runner-status-notifier.git
cd github-runner-status-notifier/scripts

2. Create the .env file

cp .env.example .env

Edit .env and fill in your values:

Variable	Description
GITHUB_TOKEN	GitHub PAT with read:org, read:actions, metadata scopes
REPO_OWNER	GitHub organization or username
REPOS	Bash array of repository names to monitor
CLICKUP_TOKEN	ClickUp API token
CLICKUP_WORKSPACE_ID	ClickUp workspace ID
CLICKUP_CHANNEL_ID	ClickUp chat channel ID
RUNNER_NAME_PREFIX	Prefix to match runner names (default: self-hosted-linux)
FAILURE_TIME_WINDOW_MINUTES	Minutes to look back for failures (default: 10)

3. Make the script executable

chmod +x check.sh

4. Run it

# Normal mode (silent unless there are notifications)
./check.sh

# Debug mode (verbose output)
./check.sh --debug

5. Schedule with cron (recommended)

# Run every 5 minutes
*/5 * * * * /path/to/scripts/check.sh

---

Creating the GitHub Access Token (PAT)

Create a Fine-grained Personal Access Token from: https://github.com/settings/personal-access-tokens

Required scopes

• read:org - Read organization settings
• read:actions - Access runner and workflow status
• metadata - Required for API access

This token does not have write permissions, making it safe for read-only monitoring.

---

How It Works

State Tracking

The script persists state in a local JSON file (.check_state.json) between runs. This enables smart alerting:

• Runner: Notifies only on transitions (online -> offline, offline -> online)
• Queued workflows: Notifies when workflows enter the queue, and when the queue clears
• Failed workflows: Notifies once when failures appear within the time window

API Calls

1. GET /orgs/{org}/actions/runners - Check runner status
2. GET /repos/{owner}/{repo}/actions/runs?per_page=10 - Check workflow runs per repo

Each API call validates the HTTP status code and expected response structure. On failure, a dedicated error alert is sent to ClickUp.

Notifications

Messages are sent to ClickUp via: POST /api/v3/workspaces/{id}/chat/channels/{id}/messages

Format: Markdown (content_format: "text/md")

---

Dependencies

• bash 4+
• curl
• jq

---

Documentation & References

• GitHub REST API - Self-hosted Runners
• GitHub REST API - Workflow Runs
• ClickUp API - Chat Messages

---

License

Licensed under the GNU General Public License v3.0. See LICENSE for details.