README.org

 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][https://toolbox.marketingtools.apple.com/api/v2/badges/download-on-the-app-store/black/en-us]]
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 repositories, recent activity, and the unread count       |
16| Repositories              | File tree and blob view with syntax highlighting, history at a ref or per file, blame, branches and tags, file editing on a branch, and a compare between any two refs |
17| Merge requests            | Lists and detail with a unified diff, comments and review threads, review verdicts and requests, draft and ready, retarget, milestones, and the stack a merge request sits in |
18| Issues                    | Lists and detail, comments, 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, and the whole instance for repositories, issues and merge requests |
20| Notifications             | The inbox, unread or all, marked read singly or in bulk                                                                            |
21| Repository actions        | Fork, bookmark, watch and mute, pin, archive, visibility, topics, branch protection, and dependency checks with their status       |
22| Builds                    | Build list, job picker, logs, and cancelling one that is queued or running                                                          |
23| Releases and wiki         | Releases list, detail, create, 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 what is SSH-only by
30design: minting an API token, and deleting or transferring a repository,
31both of which want a typed confirmation or carry a credential.
32
33* Signing in
34
35As =gitbay= requires, your SSH key is your identity. To login to the mobile app,
36you will need to mint a bearer token:
37
38#+begin_src sh
39gitbay auth token create --name iphone --scope full --ttl 90d
40#+end_src
41
42Alternatively, =--scope read= works too, but a read-only token cannot comment or
43merge.
44
45Any gitbay instance works. You just need to enter the host at sign-in.
46
47* Building
48
49Builds with the iOS 26.5 SDK and runs on iOS 18.0 and later. Swift 6 language mode, default =MainActor=
50isolation.
51
52#+begin_src sh
53xcodebuild -project gitbay.xcodeproj -scheme gitbay \
54  -destination 'platform=iOS Simulator,name=iPhone 17' build
55#+end_src
56
57Dependencies resolve over SSH ([[https://gitbay.org/krz/org-swift][krz/org-swift]]) and HTTPS ([[https://github.com/raspu/Highlightr][Highlightr]]), so a key
58that can reach gitbay.org is needed to build.
59
60* Tests
61
62=gitbayTests= is hermetic and runs offline; network calls go through a stubbed
63=URLProtocol=.
64
65#+begin_src sh
66xcodebuild -project gitbay.xcodeproj -scheme gitbay \
67  -destination 'platform=iOS Simulator,name=iPhone 17' \
68  test -only-testing:gitbayTests
69#+end_src
70
71=gitbayUITests= includes a live smoke suite that talks to a real instance. It is
72opt-in, and skips without both variables. Environment reaches the test runner
73only with the =TEST_RUNNER_= prefix:
74
75#+begin_src sh
76TEST_RUNNER_GITBAY_UITEST_LIVE=1 \
77TEST_RUNNER_GITBAY_UITEST_TOKEN=<token> \
78xcodebuild -project gitbay.xcodeproj -scheme gitbay \
79  -destination 'platform=iOS Simulator,name=iPhone 17' test
80#+end_src
81
82* Contributing
83
84To contribute, create a merge request with your changes:
85
86#+begin_src sh
87gitbay mr create --source <branch> --target main --title "..."
88#+end_src