GITGUD

neiam neiam /gitgud-plasmoid

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

⭐

Log in to mark this repository.

8.0 KiB · text History 4f26744

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 and get a desktop notification when it ends. 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.

  • Watched runs are refreshed at the fast interval until they finish, whatever else the widget is doing, and are fetched by number so they’re still followed after newer runs push them off the list.
  • The watched list is saved in the widget’s config (watchedRuns), so it survives a Plasma restart or a reboot. A run that finished while Plasma wasn’t running is announced the next time it starts. A run the server no longer has (404) is quietly dropped.
  • 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.3.0
kpackagetool6 --type Plasma/Applet --install gitgud-plasmoid-0.3.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.