Connect a GitHub repository

Open the client, then the Repository tab. You can connect in one of two ways. Both are shown side by side so you can pick.

Pick a way

	GitHub App (recommended)	Access token
✅	Reaches only the repositories you pick	Works even when you can’t install apps
✅	Its tokens expire every hour; Axowl keeps no long-lived token, only the installation number	Quick for a personal repository
✅	Remove the app on GitHub and access ends at once
✅	Runs agents on GitHub Actions, watches CI and merges
✅	No token expiry to manage
⚠️	You need permission to install apps on the repository or organization. In a company organization, GitHub may ask its owner to approve	Axowl keeps the token, encrypted
⚠️		When the token expires you paste a new one
⚠️		A classic token reaches every repository you own. Use a fine-grained token instead
⚠️		No cloud runs. Agents work only through the receiver on your own computer

The GitHub App, step by step

1. Install. Press Install on GitHub. GitHub asks which repositories the app may see.
2. Pick a repository. GitHub sends you back to the same tab. Axowl first checks with GitHub that your account can reach that installation (GitHub asks you to authorize the app once for this). Then the repositories are listed. If there is only one, it is already selected. Pick one and press Connect.
3. Done. The tab shows the connected repository and its default branch.

If GitHub tells you an organization owner must approve the install, you come back to a note saying the approval is pending. Once the owner approves, press Install on GitHub again.

If the server has no GitHub App set up yet, the card stays visible but greyed out with a note. Use a token in the meantime.

A repository connected with a token can be moved to the App at any time: on the connected screen, press Reconnect through the GitHub App.

An access token, step by step

1. Paste the repository address. Any form works: https://github.com/owner/repo.git, [email protected]:owner/repo.git, owner/repo, or a link copied from the browser’s address bar such as …/owner/repo/tree/main. The tab shows the repository it read.
2. Create a token. Press Create a token.
   • For a classic token the GitHub page opens with the repo scope and the name filled in.
   • For a fine-grained token, GitHub does not accept pre-filled settings, so the tab lists exactly what to turn on, with a copy button: Repository access → Only select repositories → your repository, then Contents and Pull requests Read and write, Actions and Metadata Read-only.
3. Paste the token. The token type is set from the start of what you paste (github_pat_ is fine-grained, ghp_ is classic). The tab checks the token straight away, without saving anything, and says what to do next:
   • Read OK — press Connect.
   • Rejected — the token expired or wasn’t pasted whole. Create a new one.
   • Not found — check the address. For a fine-grained token, add the repository under Repository access.
   • Can’t read its code — set Contents to Read and write on the token.

The token is stored encrypted and never shown again.

Who may connect a repository

Connecting is a permission, so an organization admin decides who may do it. Edit it in Identity Management › Roles & Permission under Repository connection.

Permission	What it allows	Default roles
org.git_repository.create	Connect a repository — install the App or connect a token — and check a token	Owner, Admin, Team Lead
org.git_repository.delete	Disconnect a repository	Owner, Admin, Team Lead
org.git_repository.update	Turn GitHub Actions on or off for the connected repository	Owner, Admin, Team Lead
org.git_repository.read · list	See the connected repository and its secret names	Owner, Admin, Team Lead, Member
org.git_repository.propose_change	Agents open pull requests (they never push to the default branch)	Owner, Admin, Team Lead, Member

Someone without org.git_repository.create sees, instead of the two cards, a note naming the organization’s admins to ask.

API

Method	Path	Permission
GET	/api/org/{slug}/applications/{appId}/repository — status; includes canConnect and connectAdmins	org.git_repository.list
POST	…/repository/install-url — where to send the person to install the App	org.git_repository.create
POST	…/repository/installation — { installationId, code } from GitHub’s return; Axowl checks with GitHub that the signed-in person can reach the installation and binds it to this application for an hour	org.git_repository.create
GET	…/repository/candidates?installationId= — repositories the installation can see. Only a bound installation (or one this organization already connected) is accepted, otherwise 403 INSTALLATION_NOT_VERIFIED	org.git_repository.read
POST	…/repository — connect a repository picked from the candidates (same installation rule)	org.git_repository.create
POST	…/repository/verify — check an address and token without saving. Returns ok, repository, and when not ok a problem: address, no_token, rejected, not_found, contents, forbidden or other	org.git_repository.create
POST	…/repository/connect — connect with an address and token	org.git_repository.create
DELETE	…/repository — disconnect	org.git_repository.delete
GET	…/repository/secrets — which secret names the installed workflows need and which are still missing on GitHub (names only, never values)	org.git_repository.list
PUT	…/repository/actions — { "allowed": true } turns GitHub Actions on or off for the connected repository	org.git_repository.update

For running agents on GitHub Actions after connecting through the App, see Run Fledgeplan agents on GitHub Actions.