Skip to content
ZekStackPublic

About

A GitHub desktop management client for repositories, releases, and Actions across multiple organizations, with optional local Git workspace management.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Spindle

A cross-platform desktop workspace for GitHub organizations, repositories, releases and GitHub Actions — developed by ZekStack.

Spindle brings repositories, releases, and GitHub Actions from multiple GitHub organizations into one desktop workspace. Add the organizations and repositories you want to follow without a predefined catalog.

Status: active roadmap development. Spindle supports local workspaces, guarded Git tag operations and basic GitHub Release lifecycle actions. GitHub Actions management and real installed-desktop acceptance remain open. Do not use early builds as a production release automation system.

Stack

  • Electron 45, React 19, Vite 8 and TypeScript
  • TanStack Router and Query
  • Tailwind CSS 4 and shadcn-style Radix primitives
  • Hungarian and English translations, light/dark theme
  • pnpm, Linux and Windows packaging through electron-builder

Run locally

Requirements: Node.js 22.12+, pnpm 10.20.0 and a network connection. GitHub CLI is optional for public repositories; for private repositories authenticate using gh auth login or set GH_TOKEN / GITHUB_TOKEN in the launching process, not in the renderer.

corepack enable
corepack prepare pnpm@10.20.0 --activate
pnpm install
pnpm dev

Other commands: pnpm typecheck, pnpm test, pnpm build, pnpm pack:dir, pnpm pack:linux, pnpm pack:win. Native packages should be built and tested on their respective target OS.

The pnpm lockfile is committed and CI uses pnpm install --frozen-lockfile. The Windows and Linux builds are checked in CI, including a Linux Electron preload/IPC smoke test. Linux CI also installs the generated DEB on an ephemeral Ubuntu runner and verifies package ownership, version and updater identity through the packaged application. A separate Ubuntu integration job also builds two unpublished RC packages and exercises the verified Debian installer against real dpkg state, including simulated authorization denial. A dedicated Ubuntu job also exercises the real public GitHub update feed and downloads a published Debian update through the packaged application's IPC, without installing it or claiming to validate the restart flow. Windows CI likewise builds and silently installs two NSIS versions in sequence, checking the packaged updater/IPC identity and changed application payload. Another Ubuntu job launches two real AppImage builds and checks portable replacement, updater identity, running version and IPC. Two-version automatic update testing on Linux Mint, AppImage and Windows still requires human desktop QA.

First-use workflow

  1. Open Spindle's Workspace dashboard to view saved organizations and tracked repositories. Use the account button to switch GitHub identities when different repositories require different permissions.
  2. Select Add repository to search by name or directly enter owner/repository. Personal repositories and repositories from organizations you have not added are supported. For private repositories, switch to an account with access; anonymous browsing is limited to public resources.
  3. Select Add organization to browse organizations accessible to the selected GitHub account, search public organizations, or enter any organization login directly. In an organization, use the search field to find repositories across all pages, including accessible private repositories, and star useful ones. GitHub pagination controls determine whether a next page actually exists.
  4. Open a tracked repository to inspect metadata, Releases and Actions runs, or untrack it directly in the workspace. Removing an organization does not delete its independently tracked repository shortcuts.

Adding/removing a saved organization and tracking/untracking a repository only changes local workspace preferences. It never modifies GitHub organizations, memberships or repositories. Repository searches use GitHub's API, and search results depend on the selected account's permissions. GitHub authentication failures, forbidden resources, missing resources, API rate limits and connection failures display distinct, actionable errors in English and Hungarian. On a public/anonymous account, the Your GitHub organizations list requires signing in, but public organization search and public repositories remain available.

Activity and background operations

Open a repository and choose Inspect in Activity to run a real read-only inspection of its GitHub metadata, recent releases and workflow runs. The operation lives in Electron main and continues while the Activity dialog is closed. The header Activity indicator shows running jobs; its dialog supports running/history filters, progress, safe output, cancellation and repeating an inspection. Up to two inspections run concurrently.

A compact history of up to 100 operations is stored in activity-history.json in Electron user data, independently of workspace preferences. Jobs still running when the app quits are marked Interrupted when it restarts; they are not falsely marked successful. Only safe progress summaries are persisted, never GitHub tokens or raw API response bodies. The Activity dialog also provides Inspect local Git folder. Its native directory picker selects an existing Git checkout; the main-process job discovers Git and the working tree, reports the branch and staged/modified/ untracked counts, and supports cancellation and retry. Jobs use argument- array child processes with bounded output, no shell or credential prompts. Git filenames, remotes and process error text are never put in Activity history. The selected local directory is retained in the private Activity history for retry. Git subprocesses are terminated on cancellation, with a forced stop after a bounded grace period if needed.

Partial results and retry guidance: if metadata or a local Git branch is successfully inspected but a later step fails, Activity retains the successful summaries and labels the operation Partially completed rather than incorrectly reporting success or total failure. Transient network/rate-limit/timeout errors are distinguished from permissions, unavailable Git and invalid checkouts, with actionable retry guidance. Raw subprocess output and credentials are never persisted.

Local workspaces (M3.1): The Workspace dashboard lets you save multiple root directories, independent of tracked GitHub repositories. On each repository page, link a user-selected existing Git checkout via the native directory picker. Spindle verifies the worktree root and that the configured GitHub origin matches the selected owner/repository (HTTPS, SSH or scp-style SSH). You may replace or unlink a checkout, and remove root shortcuts. These actions never move, create or delete local files, and never mutate GitHub. Stale/missing paths remain visible until relinked, rather than silently selecting a different directory. Locations are saved in a separate, private Electron user-data file (local-workspaces.json), without Git credentials, remote URLs or raw Git output. Clone/fetch/fast-forward-only pull and Git tag lifecycle actions are available with Activity progress. Native OS acceptance for the complete workflow is still outstanding.

GitHub Actions workflow controls (M5.2)

The Workflows tab supports guarded manual workflow_dispatch and per-run Cancel, Rerun all jobs and Rerun failed jobs actions. For dispatch, choose an exact branch or tag, verify the workflow definition and its Git SHA, supply the inputs declared by that workflow, then confirm the selected repository, workflow and ref. Input values are kept only in transient memory and never persisted in Activity; use GitHub Actions Secrets rather than dispatch inputs for sensitive credentials.

For an existing run, Spindle asks for an explicit confirmation showing the run number, attempt, commit SHA and current state. The main process refetches the run immediately before submission; an attempt that has changed or become ineligible is rejected rather than silently retargeted. Actions write permission is required: reported OAuth scopes and repository push rights cannot prove effective Actions permissions. GitHub's API enforces the final gate, and API denials are never bypassed.

All operations create auditable Activity entries containing only safe IDs and Git SHA metadata. A confirmed POST means GitHub accepted the request, not that the remote workflow finished. Network interruption after submission is reported as uncertain; Spindle never retries a remote mutation automatically. Refresh the live Actions view to reconcile the result before another manual attempt.

Installed Linux/Windows and disposable public/private repository acceptance remains open in the roadmap.

GitHub Actions workflow discovery (M5.1)

The Workflows tab lists workflow files using GitHub's server-paginated Actions workflow API (50 per page). Select a workflow to inspect its configuration in the repository's current default branch. Spindle reads up to 128 KiB of YAML, displays declared events, simple trigger filters, workflow_dispatch input names/types/required flags/choice options, top-level GITHUB_TOKEN permissions and job overrides. It does not execute expressions or assume that requested permissions are the effective credentials at runtime. GitHub reported OAuth scopes, if available, appear separately with an explicit warning that they do not prove repository write access.

The tab also offers per-workflow run pages (30 each) with branch/tag, event and status filters, plus full commit SHA, run number, attempt and GitHub link. Workflow name/path and active-state search filters the currently loaded workflow page; it is not represented as a global repository search. API access errors and incomplete workflow files are reported, rather than being mistaken for an absence of triggers.

This stage is read-only. M5.2 introduces workflow controls; M5.3 introduces live job and log inspection. Real public/private repository and installed Windows/Linux acceptance remains in the roadmap.

Release progress and recovery (M4.4)

The Releases tab includes a read-only progress panel for previously queued tag pushes, GitHub API release changes, and workflow dispatches. Select an Activity attempt and choose Inspect / watch. Spindle queries the live remote tag ref, peeled commit, GitHub Release status and assets, and the configured workflow's recent Actions runs when possible. Current status is always distinguished from a past Activity job's local completion state.

A tag-driven Actions run is considered correlated only when its workflow, event, tag, exact commit and time window match. A manually dispatched workflow returns only an HTTP 204 acknowledgement, so a matching run may be shown as an unverified candidate, never as proven causation. If several candidates appear, no run is selected. Release publication is reported only when an actual Release is observed.

Observation uses bounded, backoff-based foreground polling: up to 30 checks and at most 10 minutes. A timeout describes the observation, not proof of remote failure. The panel can be reopened or inspected again, including after an application restart; it never retries writes and does not require background tasks. It scans at most 200 workflow runs and labels incomplete evidence explicitly. A Release and its Git tag remain independent resources; review the remote state before repeating a failed or interrupted action. No automated retry, force-push, duplicate tag or Release creation is performed.

Real disposable-repository and installed Windows/Linux acceptance still remain as roadmap gates.

Release strategies (M4.3)

Every repository's Releases tab provides a release strategy selector. The GitHub API strategy uses the existing create-draft workflow (default). The Git tag push strategy requires an existing unpublished local tag in a linked checkout; Spindle pushes it without force using the existing Git safety checks. The selected GitHub Actions workflow must actually listen to tag pushes, otherwise no run will start. Spindle does not automatically create a GitHub Release for this strategy.

The workflow_dispatch strategy selects an active workflow discovered from the repository, with an explicit branch or tag ref. Users verify the existing remote release tag and exact object/commit before confirming. Optional workflow inputs are provided as a JSON object of up to 10 string values. Values are transient and never persisted to Activity or strategy preferences. Spindle does not guess input names or triggers from workflow filenames. GitHub's 204 response confirms only that a dispatch request was accepted; it does not confirm a run or published Release.

Strategies are saved atomically in private Electron user data (release-strategies.json) and remain separate across repositories and independent of configured GitHub accounts. An active workflow may require permissions on the selected account. After a cancelled/timed-out dispatch, inspect GitHub Actions and Releases before trying again; no automatic retry occurs. End-to-end platform and live GitHub acceptance is pending.

GitHub Release management (M4.2)

From a repository's Releases tab, enter an existing remote Git tag and verify its object and exact commit SHA before creating a draft. Drafts can be edited, published as stable or prerelease, or deleted. Existing releases can have their title/notes updated and assets uploaded via the native file picker. Uploads are limited to 32 MiB per file and never overwrite an asset with the same name. Deleting a GitHub Release does not delete its Git tag, and tag deletion does not delete the Release.

Mutations re-check the selected release, remote tag SHA and modification time immediately before the GitHub API request; they are recorded in Activity without storing release notes, file paths or credentials. Cancellation or timeout may leave uncertain remote state: refresh GitHub before retrying. Publishing does not change the repository's latest-release marker. Real Windows/Linux mutation acceptance against disposable repositories is open.

Architecture and security

React renderer (no Node integration)
   -> explicit window.spindle API
Sandboxed CommonJS preload (context isolation)
   -> fixed IPC channels, main-frame origin checks
Electron main process
   -> GitHub REST API (read-only in R1)
   -> atomic local JSON preferences in Electron userData

The renderer never receives credentials, filesystem access, or a generic IPC bridge. GitHub requests use a fixed API origin, and external links are restricted to https://github.com. Local preferences are stored in the OS application data directory, not committed to the repository.

Authentication: Use the account dialog to sign in with GitHub using a GitHub OAuth application client ID and GitHub's device code flow. An OAuth app with device authorization enabled is required; enter its public client ID in the dialog or provide SPINDLE_GITHUB_CLIENT_ID. No client secret is packaged. The code appears in Spindle; approve it on GitHub in the browser. The approved token is encrypted via the OS's credential facilities and never exposed to the renderer.

Spindle can store multiple OS-encrypted GitHub accounts, switch the active account from the header, and remove individual saved accounts. The selected account is used for future GitHub API requests throughout the local workspace; the same organization and tracked-repository list is preserved across switches. An external CLI/environment mode is also selectable without deleting saved logins. On a new authorization, Spindle adds or updates only that login's encrypted token.

The active managed credential takes precedence over GH_TOKEN / GITHUB_TOKEN and GitHub CLI, which remain available as a fallback when external mode is selected. In-app sign-out removes only the selected Spindle credential. Without a secure OS credential backend—particularly on Linux where basic_text is unsafe—managed sign-in is disabled. See docs/AUTHENTICATION.md for backend details, app setup and sign-out/revocation behavior. Do not distribute PATs or package credentials with the application.

Roadmap

See docs/ROADMAP.md for staged work and acceptance gates.

Contributing

Spindle uses the MIT License. Open an issue or PR with a focused change and tests. Keep organization identifiers and release workflows configurable, avoid embedding secrets, and require an explicit confirmation for future remote mutations.

Downloadable releases

Releases are created by pushing a valid semantic version tag to GitHub. Both stable tags (v0.1.0) and release candidates (v0.1.0-rc.1) are supported. The suffix is embedded into the packaged app's version. RC releases are GitHub prereleases and do not supersede latest stable.

The Release GitHub Actions workflow builds three x64 packages on native GitHub-hosted runners and publishes them only after all builds and native tagged-package smoke checks pass (installed DEB, actual AppImage runtime and installed NSIS). These gates do not substitute for complete interactive updater QA:

OS Download
Debian / Ubuntu / Linux Mint Spindle-<version>-linux-x64.deb
Linux (portable) Spindle-<version>-linux-x64.AppImage
Windows Spindle-Setup-<version>-windows-x64.exe

Each release includes a SHA256SUMS.txt with checksums for all three packages. GitHub Actions uses contents: write only in the publishing job. Reruns resume incomplete draft uploads and verify asset SHA-256 digests; already published assets are never silently replaced.

git switch main
git pull --ff-only
git tag -a v0.1.0-rc.1 -m 'Spindle v0.1.0-rc.1'
git push origin v0.1.0-rc.1

For RC releases, Actions → Prepare RC → Run workflow provides a guarded alternative to creating/pushing the tag manually. Select main and enter an unused RC tag such as v0.1.0-rc.9. It requires green CI on the exact main commit, refuses stale/reused/non-monotonic tags, then creates the annotated tag and explicitly dispatches the Release workflow. This is an opt-in operation; merging a PR never publishes a release. If a tag already exists after a failed dispatch, manually run the Release workflow on that tag instead of moving or recreating it.

After the workflows succeed, download the packages from GitHub Releases. AppImage users should run chmod +x Spindle-*.AppImage before launch. These early builds are not code signed. Windows SmartScreen may warn, and the installers still require desktop QA prior to public promotion.

See release procedure for validation and RC rules.

Desktop auto-updates (from the next tagged release)

When Spindle launches from an installed Windows NSIS, Linux AppImage or Linux Debian package, it checks GitHub Releases for updates. If a newer compatible release is available, a dialog offers Download, followed by Install and restart when the verified download completes. Download progress and errors are visible. There are no silent downloads or installs.

Stable versions receive only newer stable releases. Users running RC builds receive newer release candidates and final releases, without downgrading. Spindle also provides a Check for updates action in its header. The update dialog can copy an allowlisted, credential-free diagnostic report for troubleshooting. Failures identify the update stage and installer format; the GitHub Releases link remains available for manual recovery.

Updaters use release metadata (latest.yml, latest-linux.yml, etc.) and verify the downloaded artifact against the recorded SHA-512 checksum. The tag-triggered release pipeline publishes these files alongside the existing .deb, .AppImage, and .exe packages.

The repository is currently private. On installed machines, Spindle reads existing gh auth token credentials or GH_TOKEN/GITHUB_TOKEN from its launching environment, without embedding secrets in installers. Private release access must be granted to the signed-in user. Public releases can be checked without authentication after the repository is published publicly.

Important: v0.1.0-rc.1 was built before auto-updates existed, so it must be upgraded manually once to an updater-enabled release. Desktop auto updates work between later releases. The first update-enabled RC should be tested on Windows, AppImage and installed .deb before public promotion.

On Debian-based Linux, updating an installed .deb may require administrator authorization. Unsigned installers and update manifests are currently verified using GitHub HTTPS and SHA-512 metadata; stronger signing and provenance are planned before general public distribution.

Linux Mint / Debian update installation

Spindle checks a downloaded DEB's published SHA-512 and verifies its package name and version before invoking the system package manager. With the new installation flow, the app waits for pkexec dpkg --install to complete, verifies the installed package version with dpkg-query, and only then relaunches. If elevation is cancelled or the package manager fails, Spindle remains open and shows an actionable error instead of restarting an unchanged version.

Spindle also records an update handoff. If it starts with the old version after an attempted update, the next launch reports the unsuccessful handoff instead of automatically showing the same update offer again.

This only applies to Spindle installed from the .deb package. The AppImage and Windows installer paths still use electron-updater's own installation logic. Running an unpacked or different executable cannot silently overwrite the installed system DEB.

If an old installed build keeps showing an update after restarting, check:

dpkg-query -W -f='${Version}\n' spindle
command -v spindle
readlink -f "$(command -v spindle)"

A newer dpkg-query version alongside an older running app usually means a different copy (for example an old AppImage) is being launched. If the system package is still old, download the new .deb from GitHub Releases and install it using your graphical package installer or:

sudo apt install ./Spindle-VERSION-linux-x64.deb

The fix is shipped only in a newer release. A running older binary cannot acquire the changed installer implementation retroactively.

Release reliability

Release tags must point to the current main commit. After merging new changes, update local main before creating the next version tag. GitHub Releases are published as drafts first, with individual resumable uploads and retries for transient GitHub API failures. A failed upload never makes an incomplete new release public. See release procedure.

About

A GitHub desktop management client for repositories, releases, and Actions across multiple organizations, with optional local Git workspace management.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages