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.
- 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
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 devOther 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.
- 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.
- 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. - 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.
- 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.
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.
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.
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.
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.
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.
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.
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.
See docs/ROADMAP.md for staged work and acceptance gates.
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.
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.1For 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.
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.
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.debThe fix is shipped only in a newer release. A running older binary cannot acquire the changed installer implementation retroactively.
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.