README.org
104 lines · 5942 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, 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 and rename |
25| Your account | SSH and PGP keys, email addresses, and your profile — description, website, about text and links |
26| Explore, feed and profiles | Discovery, activity, contribution graph |
27| 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 |
28
29Everything the CLI can do reaches the app, except minting an API token,
30which is done on the web or over SSH.
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]]), 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