GITGUD

neiam neiam /gitgud-plasmoid

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

⭐

Log in to mark this repository.

5.1 KiB · text History 010513e

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.

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.

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

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.2.0
kpackagetool6 --type Plasma/Applet --install gitgud-plasmoid-0.2.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.