GitHub repositories

Settings → Repositories holds the codebases agents in a project can work on. You connect GitHub once with the FYAI GitHub App, choose repositories on GitHub's own screen, and FYAI keeps the list in step as you change it. You then bind repositories to individual agents, so an agent knows which codebase you mean without being told in every message.

How it fits together

GitHub (you pick repositories)
        │  FYAI GitHub App installation
        ▼
Settings → Repositories   ← list kept in sync by GitHub
        │  bind on the agent's Repositories tab
        ▼
Agent ── told at the start of every chat:
         "Repositories you work on: acme/web (default branch: main) …"

An installation is the FYAI GitHub App installed on a GitHub personal account or organisation. You can connect more than one.
Each installation belongs to one FYAI project — the one you were in when you connected it. Repositories, and their bindings to agents, are per project too.
Everyone in the project can see the repository list. Changing it, which means adding, turning on, turning off or removing a repository, needs the project Admin role. Organisation Owners and Admins count as project Admins. Anyone else gets 403.
Binding a repository to an agent gives the agent context, and it also limits the agent's calls made through the FYAI GitHub App. Once an agent, or the team it's chatting in, is bound to repositories, App calls to any other repository are refused. An agent with no bound repositories isn't limited. Calls that use a stored GitHub credential, such as a token on a GitHub integration, aren't limited by the binding: that credential decides what they can read or change. See Integrations.

Connect GitHub

Open Settings. Under Project, select Repositories.
On the GitHub card, select Connect GitHub. GitHub's install screen opens in a pop-up window.
On GitHub, choose the account or organisation, then choose All repositories or Only select repositories, and install.
The pop-up closes and FYAI shows GitHub connected. The installation appears on the GitHub card, and its repositories appear in the list below.

If your browser blocks the pop-up, allow pop-ups for the FYAI site and try again.

If you aren't an owner of the GitHub organisation, GitHub sends an install request to the organisation's owners instead. FYAI shows Finished on GitHub. If an organisation owner has to approve, it will appear here once they do. The installation and its repositories appear after an owner approves it.

To connect another GitHub account or organisation, select Add another account.

Installation status

Each installation on the GitHub card shows the account name, whether it's an Organisation or Personal account, whether it covers All repositories or Selected repositories, and a status:

Status	Meaning
Connected	Active. The repository list follows what you've chosen on GitHub.
Pending	Not finished yet.
Suspended	The installation has been suspended on GitHub.
Uninstalled	The app was uninstalled on GitHub. Its repositories are turned off.

To change which repositories FYAI can reach, or to uninstall, select the external-link icon next to the installation. It opens the installation's settings on GitHub. Changes you make there flow back to the list automatically.

Manage the repository list

The list card shows how many repositories are connected. Each row shows the repository's full name (owner/name), whether it's private (lock icon) or public (globe icon), and its default branch.

Turn a repository off with its switch (project Admins only). Agents are no longer told about it. Turning it back on restores it.
Show removed includes repositories that were removed from the installation on GitHub or turned off here. They're marked removed from GitHub or turned off.
Refresh reloads the list. Right after you connect, GitHub can take a few seconds to report your repositories.

Bind repositories to an agent

Open the agent (Build → Agents) and go to its Repositories tab.
In Repositories this agent works on, choose one or more repositories.
Select Save.

At the start of every chat, the agent is told the repositories and their default branches, and that its GitHub tools should use them unless you name a different one. If a bound repository is later removed or turned off, it's highlighted on this tab, and the agent is no longer told about it. Remove it to tidy up.

If the tab says No repositories are connected to this project yet, connect GitHub first.

Bindings are stored on the agent as repository_ids, so you can also set them with PATCH /agents/{id} on the agent API.

Triggering work from GitHub events

The GitHub App connection keeps your repository list up to date; it doesn't start workflows. To run a workflow when someone pushes or opens a pull request, set up a webhook — see Webhooks and Triggering workflows with webhooks.

API

Call	Host	Purpose
`POST /github/installation/start`	Agent API	Returns `installation_url` (GitHub's install screen) and a `state`. Open the URL in a browser; the installation is linked to the project of the credential that started it.
`GET /github/installations`	Catalog API	The project's installations: `installation_id`, `account_login`, `account_type`, `repository_selection`, `status`, `claimed_at`.
`GET /repositories`	Catalog API	Active repositories. Add `include_inactive=true` to include removed ones; filter with `provider` or `integration_id`.
`GET /repositories/{id}`	Catalog API	One repository.
`PATCH /repositories/{id}`	Catalog API	Change `is_active`, `default_branch`, `description`, `html_url`, `is_private` or `integration_id`. The owner, name and provider can't be changed. Project Admin.
`POST /repositories`	Catalog API	Add a repository by hand. Project Admin.
`DELETE /repositories/{id}`	Catalog API	Remove a repository. Project Admin.

The reads are open to every member of the project. POST, PATCH and DELETE need the project Admin role (organisation Owners and Admins included) and return 403 otherwise.

installation_id is managed by FYAI: the GitHub App connection sets it when it syncs repositories and when an installation is claimed. A request that sends installation_id with anything other than the repository's current value is refused with 422 and nothing is changed, so leave it out. A repository you add by hand starts without an installation. FYAI links it if the project's GitHub App installation later reports the same repository.

Add a repository by hand

You can add repositories without the GitHub App — for example a GitLab project, or a GitHub repository your agents reach through a GitHub integration's credential:

curl -s -X POST https://catalog.fyai.co.nz/repositories \
  -H "X-API-Key: $FYAI_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "owner": "acme",
    "name": "billing-service",
    "provider": "gitlab",
    "default_branch": "main",
    "is_private": true,
    "integration_id": 31
  }'

provider is github (default) or gitlab. owner and name must each be a single path segment of letters, digits, ., _ or -. Adding a repository that's already in the project returns 409 with That repository is already connected to this project.

GitHub App tokens

When an agent's tool makes a brokered GitHub call with the FYAI GitHub App, the platform asks the Catalog API for a short-lived installation token narrowed to one repository and to the permissions that call needs. The endpoint, POST /internal/github/installation-token, is internal: it takes the platform's own secret, not an API key.

Alongside contents, pull requests, issues, Actions runs and checks, it allows GET and HEAD on the bare repository path, /repos/{owner}/{repo}, so a tool can read the default branch and description. That path gets read access to metadata only. Every other method on it is refused as unsupported_operation.
It takes an optional allowed_repository_ids list, the agent's repository binding. When it's present, the repository the path resolves to must be in the list, or the call is refused with repository_not_bound (403). Without the list the call isn't limited, and an empty list allows no repository.

Troubleshooting

Message	What to do
GitHub isn't set up on this platform yet. Ask an administrator to register the FYAI GitHub App.	The GitHub App isn't configured on this FYAI environment. Contact FYAI support.
Your browser blocked the GitHub window. Allow pop-ups for this site and try again.	Allow pop-ups for the FYAI site.
That installation is already connected to another workspace.	The GitHub installation is already linked to a different FYAI organisation or project. An installation can belong to only one.
Could not load repositories.	Select Refresh, or reload the page.
This agent is not bound to that repository: bind it on the agent's Repositories tab	The agent is bound to other repositories and its tool called one it isn't bound to. Add the repository on the agent's Repositories tab.
`403` when adding, changing or removing a repository	Only project Admins can do this. Ask one to do it.

How it fits together​

Connect GitHub​

Installation status​

Manage the repository list​

Bind repositories to an agent​

Triggering work from GitHub events​

API​

Add a repository by hand​

GitHub App tokens​

Troubleshooting​