> ## Documentation Index
> Fetch the complete documentation index at: https://plasma-ai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up GitHub

> Connect a GitHub installation, add repositories to a workspace, and give agents access.

GitHub setup has three separate steps: connect an installation, add a repository to a workspace, and give the agent access. Completing the GitHub connection does not add every repository to every workspace.

## Connect an installation

1. Open **Settings → Integrations → GitHub**.
2. Select **Connect GitHub**.
3. Complete the GitHub installation or authorization flow and choose which repositories the installation can access.
4. If Fractal asks you to choose an account, select the intended GitHub account or organization and choose **Connect**.
5. Confirm it appears under **Connected installations**.

If GitHub is not configured for your Fractal deployment, the connection action is unavailable. Contact your deployment administrator or [support](/fractal-product/support).

## Add a repository to a workspace

1. Open the intended workspace.
2. Choose **Add resource → Repository**.
3. Select **From GitHub**.
4. Choose the **GitHub account**, then search for and select the repository.
5. Review its workspace **Public** or **Private** audience and members.
6. Select **Add repository**.

Choose **From GitHub** for an existing GitHub repository; **New repository** creates a Fractal repository instead.

If the repository is missing, select **Manage access on GitHub**, update the installation's repository access, then **refresh the list**. Check the selected GitHub account as well as the repository name.

## Give an agent work

Open the attached repository and use **Add to agent** where offered, or its access controls, to add the agent as a member. Then send a concrete task that identifies the repository and expected result.

> Review this repository's onboarding flow. Explain the relevant files first, then prepare a branch and pull request for the agreed change.

Public workspace visibility allows reading within that workspace. Mutations still need participation or other applicable write authority, the agent's allowed operations, and GitHub authorization. Provider rules can further restrict pushes or merges.

The repository's Fractal audience and its visibility on GitHub are separate settings. Making the workspace attachment public does not change the repository's GitHub visibility.

## Open or clone the repository

Use **Open in GitHub** to work with the repository and its pull requests on GitHub.

**Copy my Git URL** supplies your personal connection through Fractal. Treat it as a credential and do not share it as a team URL. Each collaborator should use their own authorized access.

A GitHub-backed attachment remains a GitHub repository. The native Fractal [merge-request guide](/fractal-product/primitives/repositories) describes Fractal repositories; use GitHub's pull-request workflow for GitHub-backed work.

## Connection unavailable

If the resource shows **Connection unavailable**, reconnect the account or update the installation's repository access in GitHub settings. Workspace membership alone cannot restore revoked provider access.

A repository absent from the picker is different from a repository attached to the wrong workspace. Check installation access, workspace attachment, and agent permissions separately.

## Remove versus disconnect

| Action | Effect |
| - | - |
| **Remove from workspace** | Removes access through that workspace and revokes its Git URLs. The repository and pull requests remain on GitHub. |
| Disconnect the GitHub account | Revokes the organization's access through Fractal. Dependent workspace resources become unavailable until reconnection. Repositories remain on GitHub. |

See [Resource access and membership](/fractal-product/resource-access) and [Integration settings](/fractal-product/settings/integrations).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.