Connecting GitHub

Connecting GitHub is done once for an account or an organisation. After that a project is added by picking a repository from a list, with no address and no token, and Exeora clones, fetches and pushes with tokens that last an hour and reach that one repository. It is optional: every project works without it, with the git credentials a machine already has or with a token you give.

Connecting#

Open Settings in the dashboard and choose Connect GitHub on the GitHub card. GitHub asks where to install the Exeora app, on your own account or on an organisation, and which repositories it is given: all of them or the ones you select. Then it sends you back to the dashboard.

The way back is accepted only in a browser signed in to Exeora as the account that asked, within ten minutes, and once. A link made by one person does nothing in the browser of another. An organisation that approves installations leaves the request with one of its owners: connect again once they have approved it.

Connecting is separate from signing in. Signing in with GitHub only tells Exeora who you are, and gives it no access to any repository.

What connecting gives#

• A list to pick from. Add project in the dashboard lists the repositories you can reach, most recently pushed first. exeora project add with no argument, run outside a checkout, offers the same list in the terminal.
• No token to paste. A project picked from the list is connected to its repository. Instances on Exeora Cloud clone, fetch and push it with short-lived tokens.
• A way in for a machine that has none. On a machine of yours the same tokens are used when its own git credentials cannot reach the remote.
• gh signed in on an instance. Inside an instance on Exeora Cloud, gh acts as you.

A project becomes connected when it is picked from the list in the dashboard, or added from a machine with exeora project add while its repository is one you can reach on GitHub. Projects you already had are connected at the moment you connect GitHub, under the same condition. A project whose repository is added to the installation later is connected at that moment.

What the app is allowed to do#

The app asks for eight repository permissions, and nothing Exeora does on GitHub goes beyond them:

The tokens git uses carry the first four at most. The other four are for gh, which acts with your own token.

Accepting permissions that were added#

Issues, Actions, Checks, Commit statuses and Workflows were added after the first three. GitHub does not grant an addition by itself. It asks the owner of each installation to accept it, and until they do that installation holds what it held before:

• Everything that worked keeps working. Cloning, fetching, pushing and opening a pull request are as they were.
• gh cannot read issues, checks or workflow runs in the repositories of that installation.
• A push that changes a file under .github/workflows/ is refused by GitHub. Any other push goes through.

The GitHub card under Settings shows a notice beside an installation that has permissions pending. Review on GitHub opens that installation on GitHub, which is where its owner accepts them. Exeora cannot accept them for you. The notice goes once GitHub has told Exeora that they were accepted.

An installation that has not accepted Workflows, or was not given pull requests, still clones and pushes: Exeora asks for a token without that permission when GitHub refuses the full one. The app also receives GitHub's events about the installation and its repositories, which is how Exeora learns that a repository was renamed, removed or deleted without waiting for a clone to fail.

How tokens are scoped, and how long they last#

A token is made when git asks for one and at no other time. Git on the machine runs exeora git-credential, which asks the gateway, and the gateway asks GitHub for an installation token. Each one is:

• For one repository: the repository of the project that asked, and no other the installation holds.
• Good for an hour, which is how long GitHub makes an installation token last.
• Cut down to what you can do on GitHub yourself. Nothing for someone who can no longer read the repository. Read-only for someone who may read it and not push.

Two callers can ask for one, and nobody else: an instance on Exeora Cloud, for the one project it was made for, and your own signed-in CLI, for a project of your account. The dashboard cannot, so a token never reaches a browser.

An agent that is allowed to run commands in a project can run git there, and git can ask for a token. That is the same as on any machine that holds git credentials and lets an agent run commands. Use the project's policy to decide whether an agent may run git at all.

gh on an instance acts as you#

Git holds a token of the installation, cut down to one repository and to what git does. gh does what a person does: it reads an issue, looks at a run, comments on a pull request. So inside an instance on Exeora Cloud it acts as you, the person who owns the project, with the token GitHub gave you when you connected. gh pr list --author @me lists your pull requests, and what gh writes is written in your name.

That token reaches every repository the app is installed on that you can access, not only the project's. Anything that runs in the instance as its user can use gh with it, which includes the commands an agent runs and the project's scripts. It has one caller: the instance, for the one project it was made for. Your own CLI runs where your own gh is already signed in, and the dashboard has no use for a token, so neither is answered.

The instance asks the gateway for the token when gh runs, keeps it in memory for 30 minutes at most, and never writes it to its disk. How that works, and what gh does in a project that is not connected, is in gh on Exeora Cloud.

You reach only what you can reach on GitHub#

An installation belongs to a person or an organisation on GitHub, and it may hold many repositories. What one member of that organisation may see is a different list. Exeora asks GitHub as you, with your own token, before it lists a repository, connects a project to one, or makes a token for one. An organisation that gave the app forty repositories shows you the six you can open there.

What GitHub says about your access to a repository is remembered for ten minutes, so git does not turn every fetch into a question to GitHub. A change on GitHub therefore reaches Exeora within ten minutes.

What is stored#

• The installations your account was shown by GitHub: GitHub's id for each, the account or organisation it is on, whether it was given all repositories or selected ones, and whether it is suspended.
• Which repository each connected project is: GitHub's id for it, its full name, and whether it is private.
• Your GitHub login and the token that speaks to GitHub as you, with the token that renews it. GitHub issues the first for eight hours. Both are stored encrypted, under a key the gateway holds, and Exeora renews them before they run out. The first is handed to your instances on Exeora Cloud for gh. The one that renews it never leaves the gateway.

The tokens that clone and push are not in that list. They are made on request and written nowhere: not in the database, and not on the machine, where the credential helper answers git and stores nothing. For a connected project there is no long-lived repository token on any machine.

When access is lost#

Losing access removes nothing. The project, its locations and its working copies stay. A machine of yours keeps working with its own git credentials. An instance on Exeora Cloud can no longer fetch or push, gh there is no longer signed in, and what is already cloned on it stays readable and editable. The connection comes back when the access does: when the repository is added to the installation again, or when you connect GitHub again.

Disconnecting#

On the GitHub card under Settings, choose Disconnect beside an account. Exeora lets go of that installation, and the projects that cloned through it lose access in the way described above.

Disconnecting does not uninstall the app, because other Exeora accounts may be using the same installation. Change repositories on the same card opens the installation on GitHub, which is where the repositories it is given are changed and where the app is removed. Disconnecting also leaves your authorization of the app on GitHub as it was, which is revoked there. Exeora deletes the token it stored for you when the last account is disconnected, and also the first time GitHub refuses it.

Other Git servers#

A repository on any other Git server is a project like any other. It is added with its https address instead of being picked from a list, and the same goes for a GitHub repository on an account that has not connected.

• On a machine of yours, git uses the credentials that machine already has, over https and then over ssh. Exeora stores nothing for it.
• On Exeora Cloud, a private repository needs a token with read access to clone and write access to push. It is given when the project is added, under Another Git server in the dialog, or on standard input from the CLI. See private repositories on Exeora Cloud.

exeora project add https://git.example.com/you/repo.git --on cloud --token-stdin < token.txt

On a gateway of your own#

The GitHub card appears only on a gateway that has a GitHub App. The app's settings and the secrets it needs are in the self-hosting guide. Without them projects clone as described under other Git servers.