Skip to content

Connect GitHub for your CoAgents

View as Markdown

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.
  • You have a CoAgent to receive repository access.
  • You have the Socra CLI 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 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 with the failed operation and error, without credentials or installation URLs.

See also