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.

When SSH uses a different hostname

Some instances answer SSH on a different hostname than the web UI — remotes look like [email protected]:acme/widget.git while the instance is at https://git.example.com. The hosts do not match, so those repositories would not be found.

The extension resolves this on its own: the first time it sees an unknown remote host, it asks each configured instance for the repository and compares the ssh_url that instance advertises. On a match it records the alias in the Host Aliases preference, so every later repository on that host resolves immediately, with no further lookups and nothing to configure.

That needs a token, and the repository has to be one your token can read. If it cannot be worked out, the sidebar shows the unresolved host with an Add Host Alias… action instead of failing silently. You can also add one by hand, as remote-host = instance URL, one per line:

ssh.example.net = https://git.example.com

Aliases show under their instance in the Settings section, so a detected one is visible rather than invisible magic. =, ->, and => all work as separators, ports are ignored, and lines starting with # are comments.

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
Host Aliases	—	Map alternate remote hosts onto an instance; filled in automatically when detected
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

Three 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:

python3 Tools/make-icons.py           # regenerate
python3 Tools/make-icons.py --check    # verify, without writing

Continuous integration

.gitea/workflows/ci.yml runs the suites, syntax-checks every script, validates the manifest, and verifies the generated images on each push and pull request. Adjust runs-on if your runner registers a label other than ubuntu-latest; the jobs need only node, python3, and git.

License

MIT