README.org
104 lines · 6546 bytes
1#+title: gitbay-ios
2#+author: Christian Cleberg
3
4A native iOS client for [[https://gitbay.org][gitbay]], a CLI-first git forge.
5
6This app is a reading, reviewing and responding surface for the times you are
7not at a keyboard.
8
9[[https://apps.apple.com/us/app/gitbay/id6806399095][Download on the App Store]]
10
11* What it does
12
13| Area | What's there |
14|---------------------------+------------------------------------------------------------------------------------------------------------------------------------|
15| Dashboard | Your review queue, assigned work, open merge requests and issues, pinned saved queries, pinned repositories, recent activity, and the unread count |
16| Repositories | File tree and blob view with syntax highlighting and names linked to their definitions, history at a ref or per file, blame, branches and tags, file editing on a branch, a compare between any two refs, and finding a definition from the symbol index |
17| Merge requests | Lists and detail with a unified diff, comments and review threads started from a diff line, suggested changes and applying them, reactions, review verdicts and requests, draft and ready, retarget, milestones, merge when ready, and the stack a merge request sits in |
18| Issues | Lists and detail, comments, reactions, labels with the colours the web paints them, assignees and milestones, filtering by label, assignee, author and milestone |
19| Search | Title-and-body search within a repository, file contents across one repository, the whole instance for repositories, issues and merge requests, and saved queries across repositories |
20| Notifications | The inbox, unread or all, marked read singly or in bulk. Push registers this device against every signed-in account; a tap opens the issue, merge request or build it names |
21| Repository actions | Fork, bookmark, watch and mute, pin, archive, visibility, topics, branch protection, required checks, dependency checks with their status, build secrets, deploy keys, mirrors, custom pages domains, rename, transfer and delete |
22| Builds | Build list, job picker, logs whole or their last lines, and cancelling one that is queued or running |
23| Releases and wiki | Releases list, detail, create with notes summarized from merged merge requests, edit and delete. Wikis read from the same instance |
24| Organisations | Members and roles, teams and their repository grants, create, rename and delete |
25| Your account | SSH keys with their last use and expiry, PGP keys, email addresses, API tokens, browser sessions, notification settings including reply by mail, your profile — description, website, about text and links — and deleting the account |
26| Explore, feed and profiles | Discovery, activity, contribution graph |
27| Administration | For instance admins: worker queues, accounts with their detail, limits, roles and state, creating, deleting and inviting, repositories with archive, visibility, reindex and delete, organization limits, statistics, the audit log, runners, the reply mailbox and pruning a merge request's head |
28| Markup | Bodies and comments are written and rendered in the format they were stored in. Org renders natively through [[https://gitbay.org/krz/org-swift][OrgSwiftUI]] — selectable text, Dynamic Type, VoiceOver — rather than in a web view. TeX math in either format is typeset with [[https://github.com/mgriebling/SwiftMath][SwiftMath]] by the web's rules |
29
30Everything in your account the CLI can do reaches the app.
31
32* Signing in
33
34To sign in to the mobile app you need a bearer token. Create one with full
35scope under Settings → API tokens on the instance's website
36(=https://<instance>/settings#tokens=), or over SSH:
37
38#+begin_src sh
39gitbay auth token create --name iphone --scope full --ttl 90d
40#+end_src
41
42Full scope can comment and merge, and on an admin account, administer the
43instance. =--scope read= works too, but a read-only token cannot comment or
44merge.
45
46Any gitbay instance works. You just need to enter the host at sign-in.
47
48* Building
49
50Builds with the iOS 26.5 SDK and runs on iOS 18.0 and later. Swift 6 language mode, default =MainActor=
51isolation.
52
53#+begin_src sh
54xcodebuild -project gitbay.xcodeproj -scheme gitbay \
55 -destination 'platform=iOS Simulator,name=iPhone 17' build
56#+end_src
57
58Dependencies resolve over SSH ([[https://gitbay.org/krz/org-swift][krz/org-swift]]) and HTTPS ([[https://github.com/raspu/Highlightr][Highlightr]], [[https://github.com/mgriebling/SwiftMath][SwiftMath]]), so a key
59that can reach gitbay.org is needed to build.
60
61* Tests
62
63=gitbayTests= is hermetic and runs offline; network calls go through a stubbed
64=URLProtocol=.
65
66#+begin_src sh
67xcodebuild -project gitbay.xcodeproj -scheme gitbay \
68 -destination 'platform=iOS Simulator,name=iPhone 17' \
69 test -only-testing:gitbayTests
70#+end_src
71
72=gitbayUITests= includes a live smoke suite that talks to a real instance. It is
73opt-in, and skips without both variables. Environment reaches the test runner
74only with the =TEST_RUNNER_= prefix:
75
76#+begin_src sh
77TEST_RUNNER_GITBAY_UITEST_LIVE=1 \
78TEST_RUNNER_GITBAY_UITEST_TOKEN=<token> \
79xcodebuild -project gitbay.xcodeproj -scheme gitbay \
80 -destination 'platform=iOS Simulator,name=iPhone 17' test
81#+end_src
82
83The suite runs as the =ios-smoke= account, not a personal one: it owns the
84scratch and fixture repositories and is an admin of =krz=. An instance admin
85provisions it once with =gitbayUITests/smoke-account.sh=, which also writes the
86account's SSH key to =~/.ssh/gitbay-ios-smoke=. The token above is minted with
87that key:
88
89#+begin_src sh
90ssh -F /dev/null -i ~/.ssh/gitbay-ios-smoke -o IdentitiesOnly=yes \
91 git@gitbay.org token create --name ui-smoke --scope full --ttl 30d
92#+end_src
93
94Setup signs in only when it finds the token screen, so a simulator signed in as
95another account has to be signed out first (=xcrun simctl keychain <device>
96reset= while the app is not running).
97
98* Contributing
99
100To contribute, create a merge request with your changes:
101
102#+begin_src sh
103gitbay mr create --source <branch> --target main --title "..."
104#+end_src