Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 74 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,78 @@

A small, local-first Chrome / Chromium extension for GitHub's published service health. Manifest V3, no account, no backend, no telemetry.

The first version includes the overall status, affected-first service list, active incidents and scheduled maintenance, a colored toolbar marker with textual badge, background polling, persistent cache, manual refresh, system/light/dark themes, and update interval settings. Only `storage`, `alarms`, and access to `https://www.githubstatus.com/*` are requested.
The first version includes the overall status, affected-first service list, active incidents and scheduled maintenance, a GitHub toolbar icon colored by status, background polling, persistent cache, manual refresh, system/light/dark themes, and update interval settings. Only `storage`, `alarms`, and access to `https://www.githubstatus.com/*` are requested.

## Build and install
## Install a release in Chrome

Download a ready-to-use ZIP from [GitHub Releases](https://github.com/cpanato/github-status-extension/releases). You do not need Node.js, Go, npm, or a copy of the source repository to use a release.

### Choose where to keep the extension

Chrome loads an unpacked extension directly from the folder you select. **Keep that extracted folder in a permanent location while the extension is installed.** The ZIP can be deleted after extraction.

Suggested locations for this project:

| System | Suggested installation folder |
| ------- | ---------------------------------------- |
| macOS | `~/Applications/github-status-extension` |
| Linux | `~/.local/share/github-status-extension` |
| Windows | `%LOCALAPPDATA%\GitHubStatusExtension` |

These are suggestions, not required Chrome locations. You can choose another permanent folder, including a directory on another drive. The destination is selected when you click **Load unpacked**; there is no installation-path setting inside the extension. Use the same folder for later updates. Chrome manages its own profile folders; you do not need to copy files into them.

### Download, extract, and load

1. Open the release you want to test. Under **Assets**, download `github-status-extension-<version>.zip` and, optionally, its matching `.zip.sha256` checksum. The automatically generated **Source code** archives contain the development source, not the ready-to-use extension.
2. Create your permanent installation folder and extract the ZIP contents into it.
3. Check that `manifest.json` is directly inside that folder:

```text
github-status-extension/
manifest.json
popup.html
options.html
background/
icons/
ui/
...
```

4. Open `chrome://extensions` in Chrome and enable **Developer mode**.
5. Click **Load unpacked** and select the folder containing `manifest.json`.
6. Open Chrome's extensions menu (the puzzle icon), find **GitHub Status Indicator**, and pin it to the toolbar. Click the GitHub icon to view status; use the gear in the popup for preferences.

On macOS, for example, after downloading the ZIP to Downloads:

```bash
release_version=0.1.0-rc.3 # Replace with the version you downloaded.
extension_dir="$HOME/Applications/github-status-extension" # Change to your preferred folder.
mkdir -p "$extension_dir"
unzip "$HOME/Downloads/github-status-extension-$release_version.zip" -d "$extension_dir"
open "$extension_dir"
```

In Chrome, select that `github-status-extension` folder. In the folder picker, **Command–Shift–G** lets you paste its full path. For the suggested location, enter `~/Applications/github-status-extension`.

For an optional checksum check on macOS, keep the ZIP and its checksum in the same directory and run:

```bash
cd "$HOME/Downloads"
release_version=0.1.0-rc.3 # Replace with the version you downloaded.
shasum -a 256 -c "github-status-extension-$release_version.zip.sha256"
```

### Update an installed release

1. Download the next release's ZIP and extract its contents into the **same installation folder**, replacing the existing extension files. Keep `manifest.json` at the same location; avoid adding a nested folder named after the new version.
2. Open `chrome://extensions`, find **GitHub Status Indicator**, and click its **Reload** button (the circular arrow).
3. Open **Details** to check the displayed version, then open the popup to confirm the update. Use **Reload** for updates rather than removing and re-adding the extension.

Updates are manual while releases are installed this way. If you move or delete the extracted folder, Chrome can no longer load that installation. Choose the permanent location before the first install; keep Downloads and temporary build/worktree directories for downloads and development.

This uses Chrome's documented [Load unpacked and Reload workflow](https://developer.chrome.com/docs/extensions/get-started/tutorial/hello-world#load-unpacked), also used for local builds of extensions such as [Bitwarden](https://contributing.bitwarden.com/getting-started/clients/browser/) and [Stylus](https://github.com/openstyles/stylus/wiki/Install-Stylus-from-GitHub).

## Build from source (development)

Requires Node.js 26 LTS or newer and npm. The `.nvmrc` file selects Node 26 for local development and CI; run `nvm install && nvm use` if you use nvm. Bash, jq, zip, and shasum are used for packaging.

Expand All @@ -13,7 +82,7 @@ npm ci --ignore-scripts
npm run build
```

Open `chrome://extensions`, enable **Developer mode**, choose **Load unpacked**, and select this worktree's `dist` directory. Pin **GitHub Status Indicator** to the toolbar. No login or configuration is needed. Open settings using the gear in the popup.
For development, open `chrome://extensions`, enable **Developer mode**, click **Load unpacked**, and select the generated `dist` directory inside your checkout/worktree. This directory contains `manifest.json`. Rebuild and click **Reload** after code changes. For an installation independent of the checkout, copy the contents of `dist` into your chosen permanent folder and follow the release installation steps above.

```bash
npm run package
Expand All @@ -29,7 +98,7 @@ The dedicated Release workflow runs only when a version tag is pushed; it has no

The repository enables release immutability. Publication creates a draft, uploads every asset, downloads and verifies the uploaded package, and only then publishes the draft. Published assets and tags are never replaced. If publication fails, the release stays unpublished; fix the issue and cut a new RC instead of overwriting assets. Future cosign signatures must be included before publication.

To test a published RC, download and extract its ZIP, open `chrome://extensions`, enable **Developer mode**, and choose **Load unpacked** with the extracted directory. To verify the download, put the ZIP and checksum in the same directory and run `shasum -a 256 -c github-status-extension-0.1.0-rc.1.zip.sha256`.
To test a published RC, follow [Install a release in Chrome](#install-a-release-in-chrome) above. RC and stable ZIPs use the same installation and update procedure.

To prepare an RC locally without publishing:

Expand Down Expand Up @@ -58,6 +127,7 @@ Playwright loads the built extension into a real Chromium profile. Tests replace

- The default check interval is one minute; settings offer 1, 2, 5, or 10 minutes. Chrome can delay alarms during sleep. Freshness is checked whenever the worker or popup runs.
- A failed check retains the last successful snapshot, marks it stale, and changes the toolbar to unknown. Expired data is never treated as fresh operational status. Cached service rows are labeled explicitly.
- The GitHub toolbar icon is green for operational status, yellow for degraded performance or maintenance, red for partial or major outages, and gray for unknown, stale, or failed checks. Attention/outage badges and tooltip text provide status information beyond color. The Chrome Extensions page uses a neutral GitHub icon. Icon sources and regeneration instructions are in [assets/README.md](assets/README.md).
- Manual refresh respects the next permitted check time. Failed checks use exponential backoff with jitter and honor bounded `Retry-After` values. Requests time out after ten seconds, reject redirects, omit credentials, and cap response size at 1 MiB.
- The summary API supplies unresolved incidents, not resolved incident history. This MVP does not request extra historical feeds or invent uptime metrics.
- GitHub is the only configured source in this release. Multiple sources, GitLab, and runtime host permissions are deferred to later milestones. The normalized domain and provider interface are separate from the GitHub schema.
Expand Down
19 changes: 19 additions & 0 deletions assets/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# GitHub icon source

`mark-github.svg` is the official `mark-github-16` icon from [Primer Octicons](https://github.com/primer/octicons). The exact source revision is recorded in `octicons-commit.txt`. Its MIT license is bundled in `public/licenses/octicons-LICENSE.txt` and included in the extension package.

`mark-github-mask.png` is a 512 × 512 black-on-white rasterization of that SVG. It is a build source, not a runtime asset. The Go generator converts coverage to transparency and produces neutral application icons plus green, yellow, red, and gray toolbar variants. PNGs are committed so building the extension does not require Go or browser-based asset generation.

Regenerate the color variants from the mask with:

```bash
go run scripts/icons.go
```

To regenerate the mask, use the installed Playwright Chromium (the same external tool used for browser tests):

```bash
sed 's/width="16" height="16"/width="512" height="512"/' assets/mark-github.svg > /tmp/github-status-mark.svg
npm exec --no -- playwright screenshot --channel chromium --viewport-size '512,512' file:///tmp/github-status-mark.svg assets/mark-github-mask.png
go run scripts/icons.go
```
Binary file added assets/mark-github-mask.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions assets/mark-github.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions assets/octicons-commit.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
b3e95564299217e1bcc6cd07d62e57d74fb9bc09
Binary file modified public/icons/128.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified public/icons/16.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified public/icons/32.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified public/icons/48.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/icons/attention-16.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/icons/attention-24.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/icons/attention-32.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/icons/operational-16.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/icons/operational-24.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/icons/operational-32.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/icons/outage-16.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/icons/outage-24.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/icons/outage-32.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/icons/unknown-16.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/icons/unknown-24.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/icons/unknown-32.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
21 changes: 21 additions & 0 deletions public/licenses/octicons-LICENSE.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 GitHub Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
6 changes: 5 additions & 1 deletion public/manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,11 @@
"action": {
"default_popup": "popup.html",
"default_title": "GitHub: Status Unavailable",
"default_icon": { "16": "icons/16.png", "32": "icons/32.png" }
"default_icon": {
"16": "icons/unknown-16.png",
"24": "icons/unknown-24.png",
"32": "icons/unknown-32.png"
}
},
"icons": {
"16": "icons/16.png",
Expand Down
98 changes: 82 additions & 16 deletions scripts/icons.go
Original file line number Diff line number Diff line change
@@ -1,25 +1,91 @@
//go:build ignore

// Generate the extension's local PNG assets with the Go standard library.
// Generate transparent GitHub status icons from the checked-in Octicons mask.
package main

import (
"fmt"
"image"
"image/color"
"image/png"
"os"
"fmt"
"image"
"image/color"
"image/png"
"os"
)

func main() {
for _, size := range []int{16, 32, 48, 128} {
img := image.NewNRGBA(image.Rect(0, 0, size, size))
for y := 0; y < size; y++ { for x := 0; x < size; x++ {
dx, dy := float64(x)-float64(size-1)/2, float64(y)-float64(size-1)/2
if dx*dx+dy*dy < float64(size*size)*.21 { img.Set(x,y,color.NRGBA{R:110,G:119,B:129,A:255}) }
if dx*dx+dy*dy < float64(size*size)*.025 { img.Set(x,y,color.NRGBA{R:255,G:255,B:255,A:255}) }
} }
f, err := os.Create(fmt.Sprintf("public/icons/%d.png",size)); if err != nil { panic(err) }
if err := png.Encode(f,img); err != nil { panic(err) }; if err := f.Close(); err != nil { panic(err) }
}
if err := generate(); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}

func generate() error {
f, err := os.Open("assets/mark-github-mask.png")
if err != nil {
return err
}
mask, err := png.Decode(f)
closeErr := f.Close()
if err != nil {
return err
}
if closeErr != nil {
return closeErr
}
palette := map[string]color.NRGBA{
"operational": {R: 35, G: 134, B: 54, A: 255},
"attention": {R: 191, G: 135, B: 0, A: 255},
"outage": {R: 207, G: 34, B: 46, A: 255},
"unknown": {R: 110, G: 119, B: 129, A: 255},
}
for name, tint := range palette {
for _, size := range []int{16, 24, 32} {
if err := writeIcon(mask, tint, size, fmt.Sprintf("public/icons/%s-%d.png", name, size)); err != nil {
return err
}
}
}
for _, size := range []int{16, 32, 48, 128} {
if err := writeIcon(mask, palette["unknown"], size, fmt.Sprintf("public/icons/%d.png", size)); err != nil {
return err
}
}
return nil
}

func writeIcon(mask image.Image, tint color.NRGBA, size int, path string) error {
out := image.NewNRGBA(image.Rect(0, 0, size, size))
bounds := mask.Bounds()
// Area-average the high-resolution mask with transparent padding. This keeps
// the GitHub silhouette legible at 16px and avoids clipping its outer circle.
const samples = 32
for y := 0; y < size; y++ {
for x := 0; x < size; x++ {
var coverage uint64
for sy := 0; sy < samples; sy++ {
for sx := 0; sx < samples; sx++ {
u := (float64(x) + (float64(sx)+0.5)/samples) / float64(size)
v := (float64(y) + (float64(sy)+0.5)/samples) / float64(size)
u = (u-0.5)/0.9 + 0.5
v = (v-0.5)/0.9 + 0.5
if u < 0 || u >= 1 || v < 0 || v >= 1 {
continue
}
p := color.GrayModel.Convert(mask.At(bounds.Min.X+int(u*float64(bounds.Dx())), bounds.Min.Y+int(v*float64(bounds.Dy())))).(color.Gray)
coverage += uint64(255 - p.Y)
}
}
pixel := tint
pixel.A = uint8((coverage + samples*samples/2) / (samples * samples))
out.SetNRGBA(x, y, pixel)
}
}
f, err := os.Create(path)
if err != nil {
return err
}
if err := png.Encode(f, out); err != nil {
_ = f.Close()
return err
}
return f.Close()
}
22 changes: 4 additions & 18 deletions src/background/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import {
ProviderError,
type StatusProvider,
} from "../providers/github.js";
import { readCache, readSettings } from "../storage.js";
import { emptyCache, readCache, readSettings } from "../storage.js";
import { fetchCache } from "./polling.js";
const alarmName = "github-refresh";
let inFlight: Promise<Cache> | undefined;
Expand All @@ -20,19 +20,8 @@ const authorizedProvider: StatusProvider = {
};
async function updateToolbar(cache: Cache) {
const state = toolbar(cache);
const canvas = new OffscreenCanvas(32, 32);
const ctx = canvas.getContext("2d")!;
ctx.fillStyle = state.color;
ctx.beginPath();
ctx.arc(16, 16, 13, 0, Math.PI * 2);
ctx.fill();
ctx.fillStyle = "#ffffff";
ctx.font = "bold 23px sans-serif";
ctx.textAlign = "center";
ctx.textBaseline = "middle";
ctx.fillText(state.text, 16, 17);
await Promise.all([
chrome.action.setIcon({ imageData: ctx.getImageData(0, 0, 32, 32) }),
chrome.action.setIcon({ path: state.icon }),
chrome.action.setTitle({ title: state.title }),
chrome.action.setBadgeText({
text: state.state === "operational" ? "" : state.text,
Expand Down Expand Up @@ -76,10 +65,7 @@ function refresh(): Promise<Cache> {
}
function run() {
void refresh().catch(() => {
/* Storage/API failures must not leave a green badge. */ void chrome.action.setBadgeText(
{ text: "?" },
);
void chrome.action.setTitle({ title: "GitHub: Status Unavailable" });
void updateToolbar(emptyCache()).catch(() => {});
});
}
chrome.alarms.onAlarm.addListener((alarm) => {
Expand Down Expand Up @@ -124,5 +110,5 @@ void (async () => {
await chrome.alarms.create(alarmName, { periodInMinutes: 1 });
run();
})().catch(() => {
void chrome.action.setBadgeText({ text: "?" });
void updateToolbar(emptyCache()).catch(() => {});
});
21 changes: 17 additions & 4 deletions src/domain.ts
Original file line number Diff line number Diff line change
Expand Up @@ -80,9 +80,9 @@ export const rank: Record<Health, number> = {
};
export const colors: Record<Health, string> = {
operational: "#238636",
maintenance: "#8250df",
degraded: "#9a6700",
partial_outage: "#9a6700",
maintenance: "#bf8700",
degraded: "#bf8700",
partial_outage: "#cf222e",
major_outage: "#cf222e",
unknown: "#6e7781",
};
Expand All @@ -97,10 +97,23 @@ export function stale(cache: Cache, now = Date.now()): boolean {
}
export function toolbar(cache: Cache, now = Date.now()) {
const state = stale(cache, now) ? "unknown" : cache.snapshot!.overall;
const icon =
state === "operational"
? "operational"
: state === "unknown"
? "unknown"
: state === "major_outage" || state === "partial_outage"
? "outage"
: "attention";
return {
state,
color: colors[state],
text: state === "operational" ? "✓" : state === "unknown" ? "?" : "!",
icon: {
16: `/icons/${icon}-16.png`,
24: `/icons/${icon}-24.png`,
32: `/icons/${icon}-32.png`,
},
text: state === "operational" ? "" : state === "unknown" ? "?" : "!",
title: `GitHub: ${labels[state]}${cache.snapshot && stale(cache, now) ? " · last known: " + labels[cache.snapshot.overall] : ""}`,
};
}
Expand Down
Loading
Loading