📡 downcheck

A simple CLI tool written in Go that monitors website availability and optionally commits the results to a git repository. By pushing results to a remote like GitHub, you can leverage built-in email notifications to get alerted when a site goes down.

⚙️ How it works

1. Sends HTTP GET requests to a list of URLs (with retries on failure)
2. Records each site's status (up/down, HTTP status code, errors)
3. Outputs results as JSON to stdout
4. Optionally commits and pushes the results to a git repository

Commit messages are prefixed with (OK) or (error) so you can quickly scan the git log for issues.

📦 Installation

make build

This produces a ./downcheck binary.

🚀 Usage

Quick check (no git)

Pass URLs directly as arguments:

./downcheck https://example.com https://google.com

With a config file

./downcheck --config=config.json

See example_config.json for the full config format:

{
  "urls": ["https://example.com", "https://google.com"],
  "git": {
    "enabled": true,
    "repo_path": "/path/to/your/status-repo",
    "remote": "origin",
    "branch": "main",
    "output_file": "downcheck/latest.json",
    "author_name": "downcheck bot",
    "author_email": "downcheck@local",
    "username": "YOUR_GIT_USERNAME",
    "token": "YOUR_PAT_OR_PASSWORD"
  }
}

Flags

Flag	Default	Description
--config		Path to JSON config file
--git-push	false	Force git commit and push (overrides config)
--out		Override output file path (relative to repo root)
--timeout	5	HTTP timeout in seconds
--retries	2	Number of retries for failed requests

📄 Output format

{
  "results": [
    {
      "url": "https://example.com",
      "up": true,
      "status_code": 200,
      "error": ""
    }
  ],
  "all_up": true,
  "timestamp": "2025-01-15T10:30:00+01:00"
}

A URL is considered "up" if it returns an HTTP status code between 200 and 399.

🔗 Git integration

When git is enabled (via config or --git-push), downcheck will:

1. Write the JSON results to the configured output_file in the target repo
2. Commit with a message like (OK): 2025-01-15T10:30:00+01:00 or (error): ...
3. Push to the configured remote and branch
4. Skip the commit if results haven't changed (no noisy duplicate commits)

Authentication uses HTTPS Basic Auth. For GitHub, set username to your GitHub username and token to a Personal Access Token with repo access.

For security, you can set the DOWNCHECK_GIT_TOKEN environment variable instead of putting the token in the config file:

export DOWNCHECK_GIT_TOKEN=ghp_your_token_here
./downcheck --config=config.json

🔔 Notifications

The key idea: by pushing results to a GitHub repository, you can use GitHub's built-in email notifications to get alerted on every status change.

To set this up:

1. Create a dedicated repository for your downcheck results (e.g. downcheck_results)
2. Go to Settings > Email notifications in that repository
3. Add your email address

Every push from downcheck will trigger an email. Since commits are prefixed with (OK) or (error), you can set up email filters to flag or highlight error notifications.

⏰ Automation

Run downcheck on a schedule using cron:

# Check every 5 minutes
*/5 * * * * /path/to/downcheck --config=/path/to/config.json >> /var/log/downcheck.log 2>&1

Or use systemd timers, launchd, or any other scheduler.