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][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 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. 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, 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 minting an API token,
 30which is done on the web or over SSH, and deleting or transferring a
 31repository, which is SSH-only by design since it wants a typed
 32confirmation.
 33
 34* Signing in
 35
 36To sign in to the mobile app you need a bearer token. Create one with full
 37scope under Settings → API tokens on the instance's website
 38(=https://<instance>/settings#tokens=), or over SSH:
 39
 40#+begin_src sh
 41gitbay auth token create --name iphone --scope full --ttl 90d
 42#+end_src
 43
 44Full scope can comment and merge, and on an admin account, administer the
 45instance. =--scope read= works too, but a read-only token cannot comment or
 46merge.
 47
 48Any gitbay instance works. You just need to enter the host at sign-in.
 49
 50* Building
 51
 52Builds with the iOS 26.5 SDK and runs on iOS 18.0 and later. Swift 6 language mode, default =MainActor=
 53isolation.
 54
 55#+begin_src sh
 56xcodebuild -project gitbay.xcodeproj -scheme gitbay \
 57  -destination 'platform=iOS Simulator,name=iPhone 17' build
 58#+end_src
 59
 60Dependencies resolve over SSH ([[https://gitbay.org/krz/org-swift][krz/org-swift]]) and HTTPS ([[https://github.com/raspu/Highlightr][Highlightr]]), so a key
 61that can reach gitbay.org is needed to build.
 62
 63* Tests
 64
 65=gitbayTests= is hermetic and runs offline; network calls go through a stubbed
 66=URLProtocol=.
 67
 68#+begin_src sh
 69xcodebuild -project gitbay.xcodeproj -scheme gitbay \
 70  -destination 'platform=iOS Simulator,name=iPhone 17' \
 71  test -only-testing:gitbayTests
 72#+end_src
 73
 74=gitbayUITests= includes a live smoke suite that talks to a real instance. It is
 75opt-in, and skips without both variables. Environment reaches the test runner
 76only with the =TEST_RUNNER_= prefix:
 77
 78#+begin_src sh
 79TEST_RUNNER_GITBAY_UITEST_LIVE=1 \
 80TEST_RUNNER_GITBAY_UITEST_TOKEN=<token> \
 81xcodebuild -project gitbay.xcodeproj -scheme gitbay \
 82  -destination 'platform=iOS Simulator,name=iPhone 17' test
 83#+end_src
 84
 85The suite runs as the =ios-smoke= account, not a personal one: it owns the
 86scratch and fixture repositories and is an admin of =krz=. An instance admin
 87provisions it once with =gitbayUITests/smoke-account.sh=, which also writes the
 88account's SSH key to =~/.ssh/gitbay-ios-smoke=. The token above is minted with
 89that key:
 90
 91#+begin_src sh
 92ssh -F /dev/null -i ~/.ssh/gitbay-ios-smoke -o IdentitiesOnly=yes \
 93  git@gitbay.org token create --name ui-smoke --scope full --ttl 30d
 94#+end_src
 95
 96Setup signs in only when it finds the token screen, so a simulator signed in as
 97another account has to be signed out first (=xcrun simctl keychain <device>
 98reset= while the app is not running).
 99
100* Contributing
101
102To contribute, create a merge request with your changes:
103
104#+begin_src sh
105gitbay mr create --source <branch> --target main --title "..."
106#+end_src