gitea-nova/README.md

Gitea for Nova

Gitea Actions, pull requests, reviews, secrets, and variables in the Nova sidebar. This extension aims to give Nova the same day-to-day coverage the official Gitea for VS Code extension gives VS Code.

Requirements

• Nova 9 or later, on macOS.
• Gitea 1.24 or later for the workflow runs API. Older servers still work: the extension falls back to /actions/tasks and shows a flat Recent Runs list.
• A personal access token, created in Gitea under Settings → Applications → Access Tokens.

Token scopes

Scope	Needed for
read:repository	Repositories, branches, pull requests
read:issue	Pull request timelines and comments
write:repository	Approving, merging, closing, review comments
read:user	Identifying the signed-in account
Actions read	Workflow runs, jobs, logs, artifacts
Actions write	Re-running and cancelling runs
Secrets / variables	Managing repository secrets and variables

Read-only tokens work fine; the write-only features simply report a clear permission error when used.

Getting started

1. Open Extensions → Gitea → Open Gitea Preferences and set your instance URL (it defaults to https://gitea.com).
2. Run Extensions → Gitea → Set Token… and paste a personal access token. Tokens are stored in the macOS Keychain, one per instance.
3. Open the Gitea sidebar.

Repositories are discovered from the git remotes of the folders in your workspace. A remote is matched to an instance by its host, so [email protected]:acme/widget.git routes to the configured instance at https://gitea.example.com. Set Discovery Mode to All Accessible Repositories to list everything your token can reach instead.

Sidebar sections

Current Branch — pull requests and workflow runs for the branch checked out in the workspace. Use the branch button in the section header (or Change Branch Filter…) to follow all branches or pin a specific one.

Workflows — every run in the repository, grouped by workflow file. Expand a run for its jobs, each job for its steps, and open the run's artifacts.

Pull Requests — open pull requests across all discovered repositories, each expanding into its reviews, review comments, and changed files.

Settings — connection state per instance, plus repository Actions secrets and variables. Secrets and variables load only when you expand them.

What you can do

• Runs — re-run a run, re-run only its failed jobs, re-run a single job, or cancel a run in progress.
• Logs — double-click a job to open its logs. With Save Job Logs to Repository on, logs are written to .tmp/gitea-logs/ so they open as real files; otherwise they open in an untitled tab.
• Artifacts — download to .tmp/gitea-artifacts/, reveal in Finder, or open (single-file artifacts are unzipped and opened directly).
• Pull requests — open a Markdown overview, open the unified diff, jump to a changed file, check out the branch, create a pull request, merge with any of Gitea's four strategies, or close.
• Reviews — approve, request changes, or comment; reply to a review comment; resolve and unresolve threads.
• Inline comments — review comments on the current branch's pull requests appear as issues in the editor gutter and the Issues sidebar, anchored to the line the comment was left on. Comments from a request changes review show as errors, others as warnings, resolved ones as info.
• Add a review comment from the editor — put the cursor on a line and use Editor → Add Gitea Review Comment….
• Secrets and variables — add, update, and delete, per repository.

Polling adapts to activity: every 15 seconds while runs are queued or running, every 60 seconds otherwise. Both intervals are configurable, and a run that finishes in a failed state posts a notification.

Multiple instances

Add extra instances under Additional Instances in preferences, or with Add Gitea Instance…. Each keeps its own Keychain token, and repositories route to whichever instance matches their remote host. The default instance is used for anything that does not match.

Differences from the VS Code extension

Nova's extension API does not expose everything VS Code's does, so a few features are shaped differently:

Gitea for VS Code	Here
Webview pull request timeline	Markdown overview opened in an editor tab
Native side-by-side diff editor	Unified .diff document, per file or whole PR
Inline comment threads on the diff	Review comments published as editor issues
Status bar run summary	Notification when a run fails
OAuth sign-in	Personal access tokens only — Nova extensions cannot run the local HTTP listener an OAuth redirect needs
tls.insecureSkipVerify	Not available; Nova's fetch has no TLS override

Preferences

Setting	Default	What it does
Default Instance URL	https://gitea.com	Instance used when no other matches a remote
Additional Instances	—	Extra instance URLs
Discovery Mode	workspace	Workspace git remotes, or all accessible repositories
Max Runs per Repository	20	How many runs to load
Max Jobs per Run	50	How many jobs to load
Active Interval	15s	Poll rate while runs are in progress
Idle Interval	60s	Poll rate when nothing is running
Notify on Failed Runs	on	Post a notification when a run fails
Show Review Comments Inline	on	Publish review comments as editor issues
Save Job Logs to Repository	on	Write logs to .tmp/gitea-logs/
Artifact Download Path	.tmp/gitea-artifacts/	Where artifacts land
Enable Debug Logging	off	Verbose extension console output

Instance URL and branch filter can also be set per workspace under Project Settings.

You will probably want to add .tmp/ to the repository's .gitignore.

Development

Symlink or copy this folder into Nova's extension directory and open the Extensions → Extension Library to load it:

ln -s "$PWD" ~/Library/Application\ Support/Nova/Extensions/unsupervised.giteanova

Turn on Enable Debug Logging and watch the extension console (Extensions → Extension Library → Gitea → Console) while working.

Tests

Tests/run.sh

Two suites run the extension's real code under plain Node against a stubbed Nova runtime and a canned Gitea instance — no install step, no network, and nothing written inside the repository. See Tests/README.md.

Images

Images/ is generated. To change an icon, edit the shapes in Tools/make-icons.py and re-run it from the extension root:

python3 Tools/make-icons.py

License

MIT