GitHub Enterprise Cloud with data residency
Connect Refactor to a GitHub you reach at your own address ending in .ghe.com. A ten-minute setup for an admin, what the app may do and why, how to check it worked, and how to remove it.
On this page8 sections
Use this page if your organization signs in to GitHub at its own address, such as acme.ghe.com. If you use github.com, see GitHub repositories instead.
What gets created#
Your GitHub is separate from github.com, so Refactor's own GitHub app cannot be installed on it. Instead, a small app is created on your GitHub, in your organization, and you stay its owner. Refactor uses it to reach the repositories you choose, and nothing else.
- You never see, copy or send a key. GitHub hands the app's key directly to Refactor, which stores it encrypted.
- No GitHub credential is ever placed in a workspace.
- You can remove the app at any time, on either side.
What the app may do, and why#
GitHub shows you this list before you create the app. Nothing is added later without your approval on GitHub.
| Permission | Access | Why |
|---|---|---|
| Metadata | Read | Required by GitHub for every app: repository names and basic details. |
| Contents | Read and write | Clone a repository into a workspace and push branches. The default branch is never pushed to. |
| Issues | Read and write | Read issues in a workspace; create and comment on them. |
| Pull requests | Read and write | Open and edit pull requests. The agent cannot merge or approve. |
| Checks | Read | Show whether a pull request's checks passed. |
| Commit statuses | Read | The same, for checks reported as statuses. |
| Actions | Read and write | See workflow runs, re-run a check, start a workflow. |
| Members (organization) | Read | Confirm that the person connecting is an owner of the organization. |
Events. The app subscribes to none. GitHub always tells an app when it is installed, suspended or removed, and when its repository list changes. Refactor uses those to show the connection as connected or disconnected.
Set it up#
- In Refactor, open Settings, then Storage. In the GitHub panel, choose Connect GitHub.
- Choose GitHub Enterprise Cloud with data residency. Enter your GitHub address (
acme.ghe.com) and the organization that will own the app, then choose Continue to GitHub. - Your GitHub opens on a page titled Create GitHub App for your organization, with the name already filled in. Choose Create GitHub App.
- You are back in Refactor. The panel says the app was created, and your address shows Ready to install. Choose Install on GitHub.
- On GitHub, choose Only select repositories or All repositories, then Install. GitHub then asks you to Authorize the app. This confirms that you own the organization; Refactor does not keep the authorization.
- You are back in Refactor. Your organization is listed with its repository count, and your address shows Connected.
If you stop part-way, the panel shows where you are (Waiting on GitHub or Ready to install) with a button to continue.
Check that it worked#
- In Refactor: the GitHub panel lists your organization as "on
acme.ghe.com" with the number of repositories, and your address shows Connected. - On GitHub: your organization's Settings, GitHub Apps lists the app as installed.
- In a workspace: open Repositories, bind one of the repositories you chose, and ask the agent to list its open issues.
Change which repositories it reaches#
In the GitHub panel, choose Manage on GitHub next to your organization. Changes take effect at once.
Remove it#
- In Refactor, in the GitHub panel, choose Remove next to your address and type the address to confirm. Workspaces lose access at once and the stored key is erased.
- On GitHub, open your organization's Settings, Developer settings, GitHub Apps, open the app, and choose Delete GitHub App under Advanced. Refactor cannot do this step for you.
Uninstalling or suspending the app on GitHub alone also stops access; Refactor then shows the connection as Disconnected.
Not supported yet#
- One GitHub per workspace. A workspace works with repositories on github.com or on your own address, not both. Use separate workspaces.
- One organization. The app works with the organization that owns it. Other organizations on your GitHub are not reached.
- Git LFS, release downloads and raw file links on your own address are not reachable from a workspace.
- GitHub Enterprise Server (GitHub you host yourself) is not supported.
Everything in What the agent can and cannot do applies here too.
If something goes wrong#
| What you see | What to do |
|---|---|
| "That setup took longer than an hour or was already used" | GitHub gives setup one hour. Delete the app on GitHub if one was created, then start again. |
| "Your GitHub would not hand the new app to Refactor without a sign-in" | Delete the app GitHub created and contact Refactor support. Your GitHub needs a different setup path. |
| "The app GitHub created could not be confirmed" | Delete the app on GitHub, then start again. |
| GitHub says the app name is taken | An earlier attempt left an app behind. Delete it under Developer settings, GitHub Apps, then start again. |
| "This workspace already works with repositories on…" | That workspace is on the other GitHub. Bind the repository in a different workspace. |
Setting up and removing are both recorded on your organization's audit record.