| 1 | --- |
| 2 | title: GitHub |
| 3 | description: Sign in with GitHub, link your account, and import repositories from GitHub through g1t's GitHub App. |
| 4 | --- |
| 5 | |
| 6 | g1t has one GitHub App, [g1t-sh](https://github.com/apps/g1t-sh). It does two |
| 7 | things: it signs you in with your GitHub account, and, once you install it |
| 8 | on a GitHub account or organization, it lets g1t read the repositories you |
| 9 | choose there and bring them across. |
| 10 | |
| 11 | ## Sign in with GitHub |
| 12 | |
| 13 | 1. On [g1t.sh/login](https://g1t.sh/login) or |
| 14 | [g1t.sh/register](https://g1t.sh/register), choose **Continue with GitHub**. |
| 15 | 2. GitHub asks you to authorize g1t. Choose **Authorize**. |
| 16 | 3. You are back on g1t, signed in. |
| 17 | |
| 18 | The first time, g1t makes your account: |
| 19 | |
| 20 | - **Username**: your GitHub login, in its own case, if it is free in any |
| 21 | case and follows g1t's rules (letters, digits and single hyphens, up to |
| 22 | 39 characters; see [creating an account](/guides/authentication/#creating-an-account)). |
| 23 | Otherwise you choose one. |
| 24 | - **Email**: the primary address on your GitHub account, if GitHub says it |
| 25 | is verified. Only verified addresses count, and GitHub's |
| 26 | `@users.noreply.github.com` relay addresses are not used. Your email is |
| 27 | confirmed already, so there is no link to follow. |
| 28 | - **Password**: none. Sign in with GitHub, or set a password later with |
| 29 | [Forgot your password](https://g1t.sh/forgot). |
| 30 | |
| 31 | Anyone can create an account with GitHub: choose **Continue with GitHub** |
| 32 | on [g1t.sh/register](https://g1t.sh/register). If someone invited you into |
| 33 | a workspace or onto a repository, open their invite link and choose |
| 34 | **Continue with GitHub** there instead, so the new account gets the |
| 35 | invitation. |
| 36 | |
| 37 | Signing in with GitHub does not start a trial or give your workspace |
| 38 | compute. That works as it does for any account: see |
| 39 | [usage and billing](/guides/usage-and-billing/). |
| 40 | |
| 41 | ### If an account already has your email |
| 42 | |
| 43 | If one of your verified GitHub addresses belongs to a g1t account that is |
| 44 | not linked to GitHub, g1t does not link them on its own: owning the GitHub |
| 45 | account does not prove you own the g1t one. g1t shows **An account with |
| 46 | this email exists. Sign in to link GitHub**. Sign in to that account with |
| 47 | its password, and GitHub is linked to it. From then on, **Continue with |
| 48 | GitHub** signs you in to it. |
| 49 | |
| 50 | The offer lasts 30 minutes. If you sign in to a different account in that |
| 51 | time, GitHub is linked to the account you signed in to. |
| 52 | |
| 53 | ## Link and unlink GitHub |
| 54 | |
| 55 | In [Settings → GitHub](https://g1t.sh/settings/github): |
| 56 | |
| 57 | - **Link GitHub** sends you to GitHub and links the account you authorize. |
| 58 | One GitHub account links to one g1t account, and the other way round. |
| 59 | - **Unlink** removes the link and ends g1t's authorization on GitHub. It is |
| 60 | refused while GitHub is the only way you sign in: set a password first. |
| 61 | - **Link again** appears when g1t's access to your GitHub account has |
| 62 | ended, for example because you revoked it on GitHub. Linking again is |
| 63 | needed to import repositories, not to sign in. |
| 64 | |
| 65 | g1t identifies your GitHub account by its numeric id, not its login, so |
| 66 | renaming yourself on GitHub keeps the link. Signing in, linking and |
| 67 | unlinking are recorded in the [audit log](/guides/audit-log/) of each |
| 68 | workspace you belong to, as `github.sign_in`, `github.linked` and |
| 69 | `github.unlinked`. |
| 70 | |
| 71 | ## Import a repository |
| 72 | |
| 73 | 1. Choose **New project**, then **Import from GitHub**. You can also go to |
| 74 | `g1t.sh/new/github`. |
| 75 | 2. A workspace owner chooses **Connect GitHub**. In one trip to GitHub, |
| 76 | g1t links your GitHub account (if it is not linked yet) and installs |
| 77 | its GitHub App on the account or organization you pick, with the |
| 78 | repositories you let it see. GitHub then returns you to the import page |
| 79 | with that account connected to the workspace. If the app is installed |
| 80 | on your GitHub account already, g1t adds that installation instead of |
| 81 | asking you to install again; with several, you choose which to add. |
| 82 | 3. Members who are not owners choose **Connect GitHub** to link their own |
| 83 | GitHub account, and import from the accounts an owner connected. |
| 84 | 4. Tick the repositories to bring across. You see only repositories that |
| 85 | both you and the app can reach. |
| 86 | 5. Choose whether to copy their issues, as [work items](/work/work-items/). |
| 87 | 6. Choose **Bring to g1t**. |
| 88 | |
| 89 | Each repository becomes a repository on g1t with the same name, private if |
| 90 | it is private on GitHub, and a [project](/guides/projects/) of its own. It |
| 91 | is copied once: the g1t repository is then its own, and you push to g1t. |
| 92 | Nothing on GitHub changes. |
| 93 | |
| 94 | ### Already installed the app on GitHub? |
| 95 | |
| 96 | g1t adds an installation to a workspace when GitHub sends you back to g1t |
| 97 | after you install the app. If you installed it on GitHub directly, in |
| 98 | another browser, or the return to g1t was lost, add it from g1t instead: |
| 99 | |
| 100 | 1. Open `g1t.sh/new/github?workspace=<workspace>` and choose **Connect |
| 101 | GitHub**. With one installation, g1t adds it straight away. |
| 102 | 2. With several, choose **Add to** the workspace beside the GitHub account |
| 103 | or organization under **Already installed on GitHub**. |
| 104 | |
| 105 | Only a workspace owner can add one, and only an installation your own |
| 106 | GitHub account can see: on your account, or on an organization you belong |
| 107 | to. |
| 108 | |
| 109 | If GitHub sends you to g1t after an installation that did not start from |
| 110 | g1t, g1t adds it to the workspace you own, or asks which one if you own |
| 111 | several, linking your GitHub account on the way if needed. It is the same |
| 112 | check: the installation must be one your GitHub account can see. |
| 113 | |
| 114 | **Choose repositories on GitHub**, beside a connected account, opens the |
| 115 | installation's settings on GitHub; saving there brings you back to the |
| 116 | import page. |
| 117 | |
| 118 | ### What comes across |
| 119 | |
| 120 | | | | |
| 121 | | --- | --- | |
| 122 | | Every branch and tag | Yes, with full history | |
| 123 | | Its description | Yes, as its [project's](/guides/projects/) description, since a repository on g1t has none of its own. Change it later in the project's **Settings → General**. | |
| 124 | | Issues | When **Copy issues too** is ticked: up to 200, oldest first, open or closed as on GitHub, with their labels (up to 10 each). Each becomes a work item of the workspace, with the new repository as its origin | |
| 125 | | Who opened an issue | Named in the work item: by their g1t username if they have linked GitHub, otherwise by their GitHub login. The work item itself is opened by you. | |
| 126 | | Milestones | Named in each work item; not copied | |
| 127 | | Issue numbers | New numbers on g1t, the workspace's next; each work item links to the original issue | |
| 128 | | Comments on issues | No | |
| 129 | | Pull requests | No. Their branches come across; open pull requests stay on GitHub. | |
| 130 | | GitHub Actions workflows | Yes, as files. Rename `.github` to `.g1t` to run them on g1t: see [GitHub Actions](/guides/actions/). | |
| 131 | | Releases, wikis, Git LFS objects | No | |
| 132 | |
| 133 | A repository is copied in one piece of at most 40 MB, after compression. |
| 134 | Push a larger one with git instead: see [git](/guides/git/). |
| 135 | |
| 136 | ## What g1t's GitHub App can do |
| 137 | |
| 138 | | Permission | Access | Why | |
| 139 | | --- | --- | --- | |
| 140 | | Contents | Read | Clone the repositories you choose. | |
| 141 | | Metadata | Read | Required by GitHub for every app: names, visibility, and whether a branch is protected. | |
| 142 | | Issues | Read | Copy issues, as work items, when you ask. | |
| 143 | | Email addresses (account) | Read | Find your verified email when you sign in. | |
| 144 | |
| 145 | The app only ever sees the repositories you or your organization's owners |
| 146 | choose on GitHub. g1t keeps your GitHub user token, which expires every 8 |
| 147 | hours, and its refresh token, encrypted at rest, and uses them only to list |
| 148 | your installations and repositories. Repository access uses short-lived |
| 149 | installation tokens, which g1t gets as the app when it needs one. |
| 150 | |
| 151 | ## Revoke or uninstall |
| 152 | |
| 153 | - **Stop signing in with GitHub**: unlink it in Settings, or revoke **g1t** |
| 154 | in GitHub under **Settings → Applications → Authorized GitHub Apps**. |
| 155 | Revoking on GitHub ends g1t's access at once; you can still sign in with |
| 156 | GitHub afterwards, which authorizes g1t again. |
| 157 | - **Stop g1t reading repositories**: uninstall the app in GitHub under |
| 158 | **Settings → Applications → Installed GitHub Apps** (for an organization, |
| 159 | its settings). Repositories already imported stay on g1t. |
| 160 | - **Change which repositories it sees**: **Choose repositories on GitHub** |
| 161 | beside the account on the import page. |
| 162 | |
| 163 | ## The webhook |
| 164 | |
| 165 | GitHub tells g1t about installations and repository changes at |
| 166 | `POST https://api.g1t.sh/hooks/github`. g1t checks each delivery's |
| 167 | `X-Hub-Signature-256` against the app's webhook secret, ignores a delivery |
| 168 | id it has already seen (`X-GitHub-Delivery`), and answers `202` before |
| 169 | acting on it. |
| 170 | |
| 171 | | Answer | When | |
| 172 | | --- | --- | |
| 173 | | `202` | Received; acted on afterwards | |
| 174 | | `200` | A delivery already received | |
| 175 | | `400` | No `X-GitHub-Delivery`, or a body that is not JSON | |
| 176 | | `401` | Not signed with the app's webhook secret | |
| 177 | | `404` | No GitHub App is configured on this g1t | |
| 178 | | `413` | A body over 10 MB | |
| 179 | |
| 180 | On your own g1t, register an app of your own: see |
| 181 | [run g1t yourself](/guides/self-hosting/#sign-in-with-github-and-import-from-github). |