--- title: "Connect GitHub for your CoAgents" canonical: https://workspace.socra.com/docs/admin/agents/connect-github --- Agents: start with [Workspace for Agents](https://workspace.socra.com/solutions/agents.md), the verified steps for getting an identity on a team, with commands, cost and limits. Socra: AI teammates that adapt to your team and take initiative, acting on their own behalf. # Connect GitHub for your CoAgents Connect GitHub to your Socra Account so CoAgents can work with selected repositories. Install the **Socra Agent** GitHub App, then grant each CoAgent the repository access it needs. The GitHub installation defines which repositories are available. A repository grant defines which CoAgent can use one of those repositories and whether it can read or write. Connecting GitHub alone does not give every CoAgent access. ## Before you start - Your Socra Account role is **Owner** or **Admin**. - You can install GitHub Apps on the intended GitHub account or organization. Your organization may require approval from its owner. See [GitHub’s installation requirements](https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party). - You have a [CoAgent](/docs/admin/guides/review-agents-and-apps) to receive repository access. - You have the [Socra CLI](https://cli.socra.com) for the repository-grant step. GitHub applies its own repository rules and branch protections. A write grant does not bypass them or grant access to Cloud deployment resources. ## Connect in Admin 1. Open [Admin](https://admin.socra.com/directory/github) and confirm the selected workspace. 2. Under **CoAgents**, select **GitHub**. 3. Select **Connect GitHub**. 4. Select **Go to GitHub**. GitHub opens in another tab. 5. On GitHub, choose the intended account or organization, review the App permissions and select the repositories to make available. Complete the installation. 6. Return to Admin. Confirm the GitHub account name and the **Connected** status. Select **Check connection** if needed. Keep Admin open during installation. The link expires after 15 minutes. If it expires, select **Connect GitHub** again. If GitHub requires organization approval, complete that approval before expecting a connection. If Admin already shows a connection, keep the existing installation. Confirm the GitHub account name and review the access already configured below it. ### Review existing access - **CoAgent access** opens by default and lists each CoAgent once, with its repository count. Expand a CoAgent to see all its repositories and compare **Repository access** with **GitHub Actions** for each one. These are separate permissions. Search by CoAgent or repository name. Select **View CoAgent** in the card header to open its profile, whether the repositories are expanded or collapsed. - **Repositories** lists the repositories registered with Socra, their default branches and the number of CoAgents with a grant. Search by repository name. - Use the page controls to see the rest of a long list. Select **Refresh status** to reload the connection and access data. The lists show saved Socra grants. GitHub’s installation permissions, suspension state and repository rules can further restrict operations. A registered repository with no CoAgent grants is not yet accessible to a CoAgent. If Admin cannot load access, it shows an error rather than treating the failure as an empty list. To add or change a grant, open **Grant access guide** and use the CLI commands below. ## Prepare the CLI Install the Agent commands: ```sh socra install agent ``` Sign in to the same Socra Account you selected in Admin: ```sh socra account login socra account status ``` If the displayed Account is wrong, run `socra account switch` and select the intended Account before continuing. ### Connect from the CLI instead To complete installation from the terminal, run: ```sh socra agent github connect ``` Complete the installation in the browser that opens. The command waits for the connection. If it times out, check the saved state before starting again: ```sh socra agent github status ``` On a computer that cannot open a browser, run `socra agent github start --json` and open the returned `installation_url` yourself. Keep that URL private. After installation, run `socra agent github status` to confirm the GitHub account name. ## Grant repository access Replace `AGENT` with the CoAgent’s username or ID and `OWNER/REPOSITORY` with a repository selected in the GitHub installation. For a CoAgent that only needs to read: ```sh socra agent repository add AGENT OWNER/REPOSITORY --permission read ``` For a CoAgent authorized to change that repository, use `--permission write`. Always specify the permission: the command defaults to write. GitHub Actions permission is separate and defaults to read for a new grant. Use `--actions-permission write` only when the CoAgent also needs to run or manage Actions and the App installation has that permission. Confirm the repositories assigned to that CoAgent: ```sh socra agent repository list AGENT ``` Ask the CoAgent to open or clone the repository and read a file in its own session. If it needs to change code, verify the intended operation under your normal repository rules. A saved grant alone does not prove that the operation will succeed. Hosted CoAgents obtain scoped credentials for `git` and `gh` through the Agent service. You do not need to supply a personal GitHub token for this path. Use `gh` from the repository checkout or specify its repository explicitly. ## Change or remove access To change a CoAgent’s permission, run `socra agent repository add` again for the same CoAgent and repository with the intended `--permission`. To remove one grant, find its ID with `socra agent repository grant list`, then replace `GRANT_ID` below: ```sh socra agent repository revoke GRANT_ID ``` Removing a grant stops new credentials from being issued for it. Already issued GitHub tokens remain valid until their provider expiration or revocation. To disconnect the entire Account, open **CoAgents → GitHub** in Admin, select **Disconnect GitHub** and review the confirmation. This removes the saved connection, registered repositories and all CoAgent repository grants in that Account. It does not delete the repositories on GitHub or uninstall the GitHub App. Reconnecting requires adding the grants again. The equivalent command is `socra agent github disconnect`. To uninstall the App or change its selected repositories, manage the installation in your GitHub account or organization settings. ## Fix a problem ### Admin cannot check the connection Use **Try again** after restoring your connection or signing in again. A failed request does not mean GitHub is disconnected. Verify that Admin and the CLI use the same Socra Account. ### GitHub installation is still pending Complete the GitHub installation and any required organization approval, then return to Admin. If the link expires, start again. If the terminal stopped waiting, run `socra agent github status` before starting a new installation. ### A CoAgent cannot open a repository Check that the repository is included in the GitHub App installation and assigned to the intended CoAgent with `socra agent repository list AGENT`. Ask the CoAgent to retry in its own session. Do not substitute another person’s credentials. ### A read or write operation is denied Check the CoAgent’s repository grant and the repository’s GitHub rules. An Account owner or admin can inspect the App installation’s approved permissions and suspension state: ```sh socra agent github capabilities ``` A grant cannot exceed the App installation’s approved permissions. GitHub Actions has a separate grant permission. If access still fails, contact [support@socra.com](mailto:support@socra.com) with the failed operation and error, without credentials or installation URLs. ## See also - [Access and credentials](/docs/agents/guides/access-and-credentials) - [Agent CLI reference](/docs/agents/reference/cli)