ghstatus

ghstatus is a lightweight client and monitor for the Github Status API as documented here. The intention of this library is to provide programmatic golang access to the API and provide monitor methods for notifications when Github is down.

The client

The client can be found in pkg/ghstatus. Using the client is pretty straightforward, as the Github Status API is read only, and no auth tokens or API keys are currently required to use it:

ctx := context.Background()
client := ghstatus.NewClient()

summaryResponse, err := client.Summary(ctx)
if err != nil {
  return fmt.Errorf("error getting client summary: %w", err)
}

...

allIncidents, err := client.AllIncidents(ctx)

...

Retry/backoff is supplied by using using Hashicorp's retryablehttp module. However, there are no documented rate limits or recommended backoff timings, so this may be overkill.

CLI

The CLI provides methods for querying the current Github Status and to output it in various formats.

Table output

Table output provides a human readable way of reading the various Github Status endpoints.

$ ghstatus summary -f table
# Status

+-----------+-------------------------+
| INDICATOR |       DESCRIPTION       |
+-----------+-------------------------+
| none      | All Systems Operational |
+-----------+-------------------------+


# Components
...

YAML output

Outputs the status in a YAML format which mirrors the native JSON format.

$ ghstatus status -f yaml
page:
    id: kctbh9vrtdwd
    name: GitHub
    url: https://www.githubstatus.com
    updated_at: 2023-05-15T07:51:14.591Z
status:
    description: All Systems Operational
    indicator: none

JSON output

Outputs the status in the native JSON format.

$ ghstatus status -f json | jq .
{
  "page": {
    "id": "kctbh9vrtdwd",
    "name": "GitHub",
    "url": "https://www.githubstatus.com",
    "updated_at": "2023-05-15T07:51:14.591Z"
  },
  "status": {
    "description": "All Systems Operational",
    "indicator": "none"
  }
}

All API query commands

All of the currently available API endpoints are queryable from the CLI utility.

$ ghstatus summary
$ ghstatus status
$ ghstatus components
$ ghstatus incidents unresolved
$ ghstatus incidents all
$ ghstatus scheduled-maintenances upcoming
$ ghstatus scheduled-maintenances active
$ ghstatus scheduled-maintenances all

Monitor

The CLI additionally supports the monitor command which can use various notifiers. The current notifiers are:

stdout

This notifier writes changes to stdout.

file

This notifier writes changes to a configured file. Requires the following flags or environment variables:

Flag	Env	Type	Description
`--fn-file-path`	`FN_FILEPATH`	string	The output file.

slack

This notifier writes changes to a Slack channel. Requires the following flags or environment variables:

Flag	Env	Type	Description
`--slack-oauth-token`	`SLACK_OAUTH_TOKEN`	string	The Slack oauth token.
`--slack-channel`	`SLACK_CHANNEL`	string	The Slack channel to post updates to. Can be either of the form `#channel-name` or the actual channel ID.
`--slack-join-channel`	`SLACK_JOIN_CHANNEL`	boolean	Whether the bot should attempt to join the channel.

The oauth token requires the following Slack scopes:

channels:join to join the target channel. This is only needed if attempting to use --slack-join-channel. If you would rather not use this, you can elect to invite the bot explicitly.
channels:read to find the target channel by its friendly name rather than the channel ID. If using a channel ID, this is not needed.
chat:write to write status messages to the channel.

mdwn / ghstatus