| 1 | --- |
| 2 | title: The phone app |
| 3 | description: g1t on Android and iOS, built with Expo. Chat with your team, live, with notifications on your phone, and Code, signed in with g1t's own OAuth. Android first, downloaded from g1t.sh while it waits for Google Play. |
| 4 | --- |
| 5 | |
| 6 | The phone app is g1t on Android and iOS, with its own screens for what |
| 7 | you do away from a desk: talking with your team in Chat, with |
| 8 | notifications on your phone, and reviewing pull requests in Code. |
| 9 | Everything else opens on the site, in your phone's browser. |
| 10 | |
| 11 | ## Install it |
| 12 | |
| 13 | Android comes first. Get it from [g1t.sh/download](https://g1t.sh/download): |
| 14 | the page opens on **Android** when you visit it on an Android phone, and |
| 15 | [g1t.sh/download?platform=android](https://g1t.sh/download?platform=android) |
| 16 | opens it from anywhere. |
| 17 | |
| 18 | 1. On your Android phone, choose **Download for Android**. On a computer, |
| 19 | scan the code beside it with the phone's camera instead. |
| 20 | 2. Open the downloaded file. Android asks once to allow your browser to |
| 21 | install apps: allow it. If Play Protect warns about an unknown app, |
| 22 | choose **More details**, then **Install anyway**. |
| 23 | 3. Open **g1t (beta)** and choose **Sign in with g1t**. |
| 24 | |
| 25 | Point at the file's name on the page to see its SHA-256, to check the file |
| 26 | you have is the one g1t published. Like every g1t build during the alpha, |
| 27 | the app isn't code-signed yet, which is why Android warns |
| 28 | ([unsigned during the alpha](/guides/desktop/#unsigned-during-the-alpha)). |
| 29 | |
| 30 | **Why a download, and not Google Play?** Google Play and the App Store |
| 31 | publish a company's apps only once it is verified with a D-U-N-S number, |
| 32 | and Flagon's is on its way. Until then the Android app is published on |
| 33 | g1t.sh, as [the desktop app](/guides/desktop/) is. It moves |
| 34 | into Google Play as soon as it can. iOS has no way in but the App Store, |
| 35 | so it follows then. |
| 36 | |
| 37 | **Updates** reach the app by themselves: most arrive the next time you |
| 38 | open it, with nothing to install. A change that needs a new install is a |
| 39 | new release on the download page; installing it over the one you have |
| 40 | keeps you signed in. |
| 41 | |
| 42 | The bar along the bottom is the site's phone bar: |
| 43 | |
| 44 | | Tab | What is on it | |
| 45 | | --- | --- | |
| 46 | | **Home** | Coming. Opens Home on the site meanwhile. | |
| 47 | | **Chat** | Your starred conversations, channels and direct messages, with what is unread, moving live. See [Chat](#chat). | |
| 48 | | **Notifications** | Coming. Opens your notifications on the site meanwhile; messages to you already arrive [on the phone](#notifications). | |
| 49 | | **Code** | The workspace's repositories, each with its pull requests and issues. A pull request shows its description, checks, conversation and changed files, and you can approve it or ask for changes. An issue shows the pull requests made for it, and you can comment. Shown when you use Code in the workspace. | |
| 50 | | **More** | Whether this phone gets notifications, your workspaces, how you signed in, and **Sign out**. | |
| 51 | |
| 52 | ## Chat |
| 53 | |
| 54 | Chat on the phone is the site's Chat: the same conversations, as they |
| 55 | happen. |
| 56 | |
| 57 | - **Conversations** show messages as the site draws them: bold, italic, |
| 58 | code, lists, quotes, tables and links, with `@mentions`, `#channels` |
| 59 | and `#123` references standing out. Messages by one person a few minutes |
| 60 | apart run together, and each day is marked. |
| 61 | - **Live.** New messages, edits, deletions and reactions appear as they |
| 62 | happen, and the line above the box says who is typing. Unread counts in |
| 63 | the list and on the **Chat** tab move as messages arrive anywhere. |
| 64 | - **Sending** shows your message at once. If it doesn't reach g1t, it |
| 65 | stays, marked **Not sent**: tap it to try again. |
| 66 | - **Long-press a message** to react, reply in a thread, copy it, or edit |
| 67 | or delete your own. Tap a reaction to add yours or take it back. |
| 68 | - **Threads** open from a message's replies, with the message they are |
| 69 | under at the top. |
| 70 | - **⋯** on a conversation stars, mutes or leaves it. |
| 71 | - **New message** (the pen at the top of Chat) messages a person, or a few |
| 72 | people together, or makes a channel. **Browse** at the |
| 73 | foot of the list joins public channels. |
| 74 | |
| 75 | A notification for a conversation you have open is not shown; one for |
| 76 | another shows as a banner at the top of the screen. |
| 77 | |
| 78 | ## Notifications |
| 79 | |
| 80 | The phone gets the same notifications as [browser push](/guides/notifications/#on-your-phone): |
| 81 | messages to you, mentions and replies in threads you are in, under the |
| 82 | same rules. Nothing comes while you are using |
| 83 | g1t in a browser or in the app itself, and nothing in |
| 84 | [Do not disturb](/guides/chat/#sounds-and-do-not-disturb). Tapping one |
| 85 | opens the conversation or thread it is about. |
| 86 | |
| 87 | The app asks to notify you the first time you sign in. To change it |
| 88 | later, use **More → Notifications on this phone**, or the phone's own |
| 89 | settings for g1t, where Android lists the **Messages** channel. Signing |
| 90 | out stops them on that phone. |
| 91 | |
| 92 | ## Signing in |
| 93 | |
| 94 | **Sign in with g1t** opens g1t.sh in your phone's browser, where you sign |
| 95 | in as usual (with your password, GitHub, two-factor) and approve the app. |
| 96 | The browser sends you back to the app, signed in. The app never sees your |
| 97 | password. This is [OAuth](/guides/authentication/#signing-in-with-oauth): |
| 98 | the app is listed as **g1t for Android** or **g1t for iOS** in |
| 99 | [Settings → Connected applications](https://g1t.sh/settings/applications), |
| 100 | where **Change access** narrows what it can do and **Sign out** ends it at |
| 101 | once. |
| 102 | |
| 103 | The approval page lists what the app asks for: reading your account, |
| 104 | workspaces, repositories, checks and workflows, reading and writing |
| 105 | issues, pull requests and notifications, and reading artifacts. Untick what you would rather it |
| 106 | could not do. |
| 107 | |
| 108 | **Use an access token** signs in with a |
| 109 | [personal access token](/guides/authentication/#access-tokens) you paste |
| 110 | in instead. The token stays on your phone, in its keystore. |
| 111 | |
| 112 | The app asks for `chat:read` and `chat:write` too. They let it use |
| 113 | Chat's routes and live connections on the site, and register for |
| 114 | notifications, and nothing else there: the app's sign-in cannot open the |
| 115 | site's pages as you. |
| 116 | |
| 117 | ## Links |
| 118 | |
| 119 | A `g1t://` link opens the app, as it opens [the desktop app](/guides/desktop/#links): |
| 120 | `g1t://acme/-/chat/dm/chn_1` is that conversation. The app shows the |
| 121 | pages it has screens for: |
| 122 | |
| 123 | | Link | Opens | |
| 124 | | --- | --- | |
| 125 | | `g1t://<workspace>/-/chat`, `…/-/chat/<channel>`, `…/-/chat/dm/<id>` | Chat, or the conversation, in that workspace | |
| 126 | | `g1t://<owner>/<repo>` | The repository | |
| 127 | | `g1t://<owner>/<repo>/pull/<number>`, `…/issues/<number>` | The pull request or issue | |
| 128 | |
| 129 | Any other page opens on the site, in the browser. |
| 130 | |
| 131 | ## Your own g1t |
| 132 | |
| 133 | The app works with a g1t you [run yourself](/guides/self-hosting/) as well |
| 134 | as with g1t.sh. It talks to one g1t at a time, and opens on g1t.sh unless |
| 135 | you point it elsewhere. Two ways to point it at yours: |
| 136 | |
| 137 | - **Scan its code.** Your g1t's download page, `<your g1t>/download`, has |
| 138 | a QR code under its platforms, **Use the phone app with** your g1t. Scan it with the phone's camera, or |
| 139 | open the page on the phone and choose **Open in the g1t app**. The app |
| 140 | asks **Use g1t.example.com?**, then signs you in there. |
| 141 | - **Type its address.** On the sign-in screen, choose **Using your own |
| 142 | g1t? Sign in there** and enter the address you open it at in a browser, |
| 143 | such as `g1t.example.com`. |
| 144 | |
| 145 | Either way the app reads `<your g1t>/.well-known/g1t.json`, where your g1t |
| 146 | says where its API is, so you never type that. A g1t from before the phone |
| 147 | app has no such file: the app then takes the API to be `api.` in front of |
| 148 | the site, and offers **Its API is at another address** if it is not. |
| 149 | |
| 150 | The sign-in screen then says **Signing in to g1t.example.com**, with |
| 151 | **Change** and **Use g1t.sh**. Switching signs you out of the g1t you were |
| 152 | on. |
| 153 | |
| 154 | | Your g1t | What to know | |
| 155 | | --- | --- | |
| 156 | | Reached by the phone | `PUBLIC_URL` and `API_URL` must be addresses the phone can open. `localhost` on a phone is the phone itself: use your computer's address on the network, or a domain. | |
| 157 | | `https` | Store builds of the app open `https` addresses only, as Android requires. A development build also opens `http`, for a g1t on your own network. | |
| 158 | | Notifications | Work with no setup: your g1t sends them through Expo's push service, as g1t.sh does. To keep notifications' words off Expo's, Google's and Apple's services, set `PHONE_PUSH=off` ([self-hosting](/guides/self-hosting/#the-phone-app)); the app then says your g1t sends no notifications, and Chat still updates while it is open. | |
| 159 | | Older versions | A g1t from before the phone app does not let the app's sign-in into Chat. Upgrade it, or sign in with an access token that has **Use the website as you**. | |
| 160 | |
| 161 | ## What's not there yet |
| 162 | |
| 163 | - **Google Play and the App Store**, once Flagon's D-U-N-S number |
| 164 | arrives ([above](#install-it)). Until then, Android from the download |
| 165 | page; iOS waits for the App Store. |
| 166 | - **Home, Notifications and Artifacts** as tabs of their own. |
| 167 | Their pages open on the site meanwhile. |
| 168 | - **Formatting in Code.** Descriptions and comments show their Markdown |
| 169 | as written; messages in Chat are formatted. |
| 170 | - **Attachments and custom emoji.** Files in messages, and a |
| 171 | workspace's own `:emoji:`, show as their names. |
| 172 | - **Replying from a notification**, without opening the app. |
| 173 | - **https links.** `g1t.sh` addresses open the site in the browser, not |
| 174 | the app, until g1t.sh publishes the files Android and iOS check first. |
| 175 | |
| 176 | ## For operators: building and releasing |
| 177 | |
| 178 | The app lives in `apps/mobile`: [Expo](https://expo.dev) with Expo |
| 179 | Router, in TypeScript, sharing types with the site through |
| 180 | `@g1t/contracts`. It builds with EAS Build. `apps/mobile/README.md` has |
| 181 | the commands for running it on a phone and the first-time setup. |
| 182 | |
| 183 | | Build | Command | What it makes | |
| 184 | | --- | --- | --- | |
| 185 | | Development | `eas build --profile development --platform android` | An APK of `g1t (dev)` (`sh.g1t.app.dev`) that loads its code from your computer. | |
| 186 | | Preview | `npm run build:android:apk -w @g1t/mobile` | An APK of `g1t (beta)` (`sh.g1t.app.preview`) to install on testers' phones. | |
| 187 | | Production | `npm run build:android -w @g1t/mobile` | An Android App Bundle of `g1t` (`sh.g1t.app`) for Google Play. | |
| 188 | |
| 189 | The three install side by side. `eas submit --platform android` sends |
| 190 | the latest production build to Google Play's internal testing track as a |
| 191 | draft, once there is a Play account to send it to. |
| 192 | |
| 193 | ### Releasing on g1t.sh/download |
| 194 | |
| 195 | Until the app is in Google Play, the `preview` build is the one people |
| 196 | install, from g1t.sh/download. A release is a tag `mobile-v<version>`, |
| 197 | where the version is `version` in `apps/mobile/app.config.ts`: push it, |
| 198 | and the `Mobile release` workflow (`.g1t/workflows/mobile-release.yml`) |
| 199 | has EAS build the APK, then publishes it to the `g1t-downloads` bucket |
| 200 | at `g1t.sh/downloads/mobile/<version>/` and points `mobile/latest.json` |
| 201 | at it, which the download page reads. `scripts/mobile-release.mjs` does |
| 202 | the same by hand (`build`, `fetch`, `manifest`, `publish`). |
| 203 | |
| 204 | | Secret or variable | What it is | |
| 205 | | --- | --- | |
| 206 | | `EXPO_TOKEN` | An Expo access token with access to the g1t project, from expo.dev | |
| 207 | | `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` | As the deploy has them | |
| 208 | |
| 209 | Most changes need no release: `eas update --channel preview` in |
| 210 | `apps/mobile` sends the app's new code to every installed copy of that |
| 211 | version, which takes it the next time it opens. A release is for a change |
| 212 | to the app's native side (a new native module, `app.config.ts`) or its |
| 213 | `version`, which is also what decides which updates a copy takes. |