GITGUD

neiam neiam /gitgud-plasmoid

public · Issues · Pulls · Labels · Forks · Compare · Actions success · Badges · Packages

⭐

Log in to mark this repository.

9.6 KiB · text History 0fc3e53

GitGud CI Widget for Plasma 6

A Plasma 6 panel widget that shows GitGud CI runs as a row of status circles.

[logo] ● ● ◉ ○
  • Logo: opens a popup with every recent run across everything you watch.
  • Circles: one per watched repository, or one per organization/user if you fold it into a single circle. The colour shows the latest run (see Statuses). Hover a circle for the workflow, run number, ref, SHA and age. Click it to open just that circle’s runs.
  • Pin (the pin button in the popup’s header, Keep Open): the popup stays open when you click elsewhere, as the system tray’s does. Click it again to unpin. The setting is remembered.
  • Run windows: break a run out of the popup into its own window. See Run windows.
  • Notify when finished: ring the bell on a run or a single job and get a desktop notification when it ends, or ask to hear about every job of a run as it finishes. See Notifications.

Statuses

Statuses read as they do in the Android app and the gg CLI.

Mark Status Meaning
green dot success
red dot failure, timed out, cancelled
pulsing orange dot running
hollow orange ring queued, blocked, waiting not started yet: waiting for a runner, for its needs, or held by its concurrency group
orange ring with a dot needs approval a fork pull request’s run, waiting for someone with write access to approve it on the pull request
grey dot skipped, superseded superseded means a newer run or job in its concurrency group replaced it. It isn’t a failure.

Only success, failure, cancelled, skipped and timed out are endings. Anything else, including a status the widget doesn’t know yet, counts as still in progress and keeps being refreshed. A run waiting for approval is refreshed at the normal pace, not the fast one, because it’s waiting on a person.

Triggers read as words: scheduled, manual (workflow_dispatch), pull request (target), branch/tag created/deleted, and after a workflow (workflow_run). A run from a fork says from a fork.

Run accordion

Runs expand the same way as in the Android app:

▸ acme/web · Build #7                        failure
  ▾ test (otp 27)   failure · 3m 0s · needs lint     ⟳
      ● Checkout
      ▾ ● Run tests
          ┌───────────────────────────────────┐
          │ …log tail…                        │
          └───────────────────────────────────┘
  • Click a run to see its jobs, artifacts, and the Re-run all, Cancel and Open buttons.
  • Click a job to see its steps. The ⟳ button re-runs only that job. Under the job’s status you’ll see why it is waiting, was skipped or was cancelled, and attempt N once it has been re-run. A dynamic matrix that hasn’t expanded yet says Matrix expands when … finish. Its jobs replace it once they’re created.
  • A fork’s run that is waiting for approval says so and links to its pull request. You approve it there.
  • Click a step to see its log slice. Failed steps open on their own.

Open runs keep refreshing while they’re in flight. Re-run and cancel are only shown when the server says you can manage the repository and the token has ci:write.

Hover a run’s row for its bell and window buttons, or right-click it for the same actions plus Open in Browser.

Run windows

Click the window button on a run (on hover, or the one next to Open once it’s expanded), or right-click → Open in Window. The run opens in a normal, resizable window titled owner/repo #12 — Build, with its own taskbar entry:

  • The header shows the workflow, repository, ref, commit, trigger, who started it, its status, age and duration, with the bell, a refresh button and Open in Browser.
  • Below it are the same jobs, steps, logs, artifacts and re-run/cancel buttons as in the popup. Jobs and steps opened in the window are open in the popup too, and the other way round.
  • While the run is in flight the window refreshes at the fast interval (While a run is in flight), even if the popup is closed and the run has dropped out of the list. Once the run finishes it stops.
  • Each run gets one window. Opening it again brings the existing window forward. Open as many runs as you like. Closing a window discards it.

Notifications

Ring the bell on a run that is still going (on hover in the popup, in the run’s window, or right-click → Notify When Finished). The bell stays lit while you’re waiting. When the run ends you get a notification such as neiam/ppl #12 failed, with the workflow, ref and duration under it and an icon for the outcome. Click it to open the run’s window, or use Open in Browser. A run is notified once and then stops being watched. Click a lit bell to stop waiting.

Jobs

  • One job: hover a job (in the popup or a run window) and ring its bell. You’re told when that job ends, e.g. neiam/ppl #12 · build (x86_64) failed, with the workflow, the job’s duration and the server’s reason if it gave one. Clicking the notification opens the run’s window with that job expanded and scrolled into view. Bell a matrix that hasn’t expanded yet and the bell moves to each of its legs once they appear. A re-run job keeps its bell too.
  • Every job of a run: right-click the run → Notify For Each Job, or tick Each job next to the bell in its window. This also watches the run. Each job is announced once as it finishes, and failures are urgent. The run’s own notification still comes last. A few things keep the noise down:
    • Jobs that had already finished when the widget first saw them aren’t announced.
    • Skipped and superseded jobs come in batches after a failure, so they aren’t announced one by one. The run’s notification counts them instead (3 skipped).
    • When more than two jobs finish between two refreshes you get one notification, e.g. neiam/ppl #12 · 3 jobs finished with a ✓, b ✓, c ✗ under it. Clicking it opens the worst of them. Jobs that finish in the same refresh as the run are listed in the run’s notification.

Watching

  • Watched runs, and the runs of belled jobs, are refreshed at the fast interval until they finish, whatever else the widget is doing. They are fetched by number, so they’re still followed after newer runs push them off the list.
  • What you’re waiting on is saved in the widget’s config (watchedRuns, eachJobRuns, watchedJobs), so it survives a Plasma restart or a reboot. A belled run or job that finished while Plasma wasn’t running is announced the next time it starts. Per-job announcements for an each-job run are not, because the widget never saw those jobs running. A run the server no longer has (404) is quietly dropped, along with its jobs.
  • Notifications go through Plasma’s own notification event, so they follow System Settings → Notifications → Plasma Workspace, including Do Not Disturb.
  • Notify when any run I triggered fails (Behavior, off by default) also notifies about failed or timed-out runs started by the token’s user. It covers runs in watched repositories that the widget saw while they were still running. A run that was already failed when the widget first saw it is not announced.

Configuration

General

  1. GitGud URL: for example https://git.example.com.
  2. Access Token: create one under Settings → API tokens (/users/settings/tokens) and tick Desktop widget. That selects repo:read, ci:read and ci:write. Leave out ci:write for a read-only widget; the re-run and cancel buttons are then hidden. A “Mobile app” token also works.
  3. Test Connection: calls /me, shows who the token belongs to, and warns about missing scopes.
  4. Watching:
    • List Repositories loads every repo and namespace the token can reach.
    • Watch all on a user or organization watches everything under it. This includes repositories created later.
      • Tick One circle to fold the namespace into a single circle. It shows the most urgent status: running, then queued, then failure, then success.
    • Add on a repository watches just that repo.
    • Or type owner/repo or owner into the field and press Add.
    • Use ↑/↓ to reorder the circles.

Behavior

Setting Default
Refresh every 60 s Idle poll, refetches every watched repo
While a run is in flight 5 s Fast poll; only refetches repos whose latest status moved or is still active
Runs listed per repository 10
Hide repositories that have never run CI on
Notify when any run I triggered fails off See Notifications

Each poll makes one /repos call, which carries every repo’s latest CI status. It then calls /repos/:owner/:name/runs only for repos that need it, so the fast poll stays cheap even when you watch a large organization.

API

The widget uses GitGud’s mobile REST API (/api/mobile/v1), which is the same surface the Android client uses. See docs/mobile-api.md in the GitGud repo.

Install

# From the source tree
kpackagetool6 --type Plasma/Applet --install .
# Upgrade after changes
kpackagetool6 --type Plasma/Applet --upgrade .

# Or build a release archive
./package.sh 0.4.0
kpackagetool6 --type Plasma/Applet --install gitgud-plasmoid-0.4.0.tar.gz

Test without installing:

plasmoidviewer -c org.kde.panel -a . -f horizontal -l topedge   # as a panel widget
plasmoidviewer -a .                            # on the desktop

License

GPL-3.0. See LICENSE.md.