> ## Documentation Index > Fetch the complete documentation index at: https://opensandbox-feat-types-open-question-labels.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # GitHub App connections > Give an agent direct Git and GitHub API access with the managed OpenComputer App A managed GitHub connection lets an agent clone repositories, push branches, use the `gh` CLI, and call GitHub's REST or GraphQL APIs as a GitHub App installation. ## Declare access Declare the permissions the agent needs and reference the connection from its agent function: ```tsx theme={null} import { defineConnection, githubApp, useConnection, } from "@opencomputer/agent"; const github = defineConnection({ id: "github", provider: githubApp({ permissions: { contents: "write", pull_requests: "write", }, }), }); export default function Agent() { useConnection(github); return "Work on the requested repository, push a branch, and open a PR."; } ``` The supported permissions are `actions`, `checks`, `contents`, `issues`, `metadata`, and `pull_requests`. `metadata` is read-only. Request only what the agent needs. GitHub access applies to the session, not to an individual render. OpenComputer mints a token with the combined permissions of the deployment's declared GitHub connections; if one declares read access and another write access for the same permission, the token requests write access. Omitting or conditionally calling `useConnection(github)` does not withhold or revoke that token. Effective authority is therefore the intersection of: * the managed OpenComputer GitHub App's permission ceiling; * the combined permissions declared in `githubApp({ permissions })`; and * the repositories selected in the attached GitHub installation. ## Install the App Deploy the agent, then connect the managed App from the project directory: ```bash theme={null} opencomputer github connect ``` Open the printed URL and install the App into a user or organization account. The CLI waits until GitHub completes the flow and, by default, attaches the installation to both development and production. Pass `--environment development` or `--environment production` to attach only one environment, or `--no-wait` when using the command in a non-interactive script. Check the result at any time with: ```bash theme={null} opencomputer github status ``` If the OpenComputer account already has one active GitHub App installation, the command attaches it directly without opening GitHub again. When multiple installations are available, select one with `--connection `; the ids and account names are shown by `opencomputer github status --json`. To install the App on another user or organization account, force a new GitHub flow and select the target account in GitHub: ```bash theme={null} opencomputer github connect --new ``` `--new` and `--connection` are mutually exclusive. Completing the new flow attaches that installation to the requested project environment or, when no environment is specified, to both environments. You can also install or attach the App from the project's **Connections** page in the OpenComputer dashboard. GitHub lets the installer select all repositories or a specific set of repositories. GitHub App access is intentionally separate from managed service OAuth. Do not use `opencomputer connection add github`; the CLI directs that command to the GitHub App flow instead. That GitHub installation selection is the complete repository boundary. There is no second OpenComputer repository allowlist. If the installer selects all repositories, the agent can access every repository available to that installation; if specific repositories are selected, it can access only those repositories. Change the selection in GitHub's installation settings. Connections are attached independently to the project's development and production environments. A session uses the installation attached to the environment it was created in: a session started as `worker@production` gets the production installation's credentials even when the same deployment is also the development alias. Promote one artifact to both environments with different installations and each environment's sessions reach only their own installation's repositories. ## List the repositories an environment can reach An application that lets a person pick a repository reads the installation's current selection from the connection rather than holding a GitHub credential of its own: ```text theme={null} GET /projects//github/repositories?environment=development&limit=100 ``` `environment` is `development` or `production` and is required. `limit` is at most 100, the default; `cursor` is the `nextCursor` of the previous page. ```json theme={null} { "repositories": [ { "id": 1296269, "fullName": "acme/service", "private": true, "defaultBranch": "main", "archived": false } ], "nextCursor": null } ``` The list is read live from GitHub each time, with a token minted for that read that can see repository metadata and nothing else. OpenComputer keeps no copy: change the selection in GitHub's installation settings and the next read shows it. Call this route from your server with an organization API key. | Status | Code | Meaning | | - | - | - | | `400` | `invalid_environment`, `invalid_limit`, `invalid_cursor` | The query is malformed | | `404` | `github_connection_not_found` | The environment has no GitHub installation attached | | `409` | `installation_suspended` | GitHub reports the installation suspended | | `502` | `github_unavailable` | GitHub could not be read; retry | ## Use Git and the API Inside the agent sandbox, ordinary GitHub tooling works directly. `gh` reads the injected `GH_TOKEN` automatically: ```bash theme={null} git clone https://github.com/acme/service.git git -C service switch -c agent/update git -C service push -u origin agent/update gh pr create --repo acme/service --fill gh api repos/acme/service/pulls ``` GitHub installation tokens expire after about one hour. Before dispatching a command, OpenComputer attempts renewal if the held token would expire within the command's allowed duration. Git and `gh` pick up a renewed token without changes to the command. Renewal uses the same declared permissions and the installation's current repository selection. If renewal fails, the command still runs with the held token and its GitHub requests may fail authentication. Detaching the connection prevents new tokens from being issued; it does not immediately revoke a token already on the computer. That token can remain usable until GitHub expires or revokes it. ### Understand GitHub permission responses Installation tokens do not have OAuth scopes. That does not mean they are unscoped. Their authority comes from the permissions included when the token is minted and the repositories granted to the installation. `X-Accepted-GitHub-Permissions` describes the permissions an API **endpoint accepts or requires**. It does not describe the permissions granted to the token. In particular, `allows_permissionless_access=true` means that endpoint does not require a specific GitHub App permission; it does not mean the token has unrestricted or “permissionless” repository access. Likewise, a `permissions` object in an ordinary repository response is not an installation token introspection result. Use installation endpoints with an installation token. For example, `GET /installation/repositories` lists the repositories available to the installation. User endpoints such as `GET /user/repos` require a user token, so a `403` from those endpoints is expected and says nothing about whether the declared installation permissions were applied. See GitHub's documentation for [generating an installation access token](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation#generating-an-installation-access-token), [troubleshooting required permissions](https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api#resource-not-accessible), and [listing repositories accessible to an installation](https://docs.github.com/en/rest/apps/installations#list-repositories-accessible-to-the-app-installation). The short-lived token is available inside the agent's sandbox as `GH_TOKEN` and `GITHUB_TOKEN`. Code running in that sandbox can read it. Do not print it, write it into source, add it to a Git remote, include it in a checkpoint, or send it to logs. Install the App only on repositories you are comfortable granting to the agent. Other `defineConnection()` providers continue to use OpenComputer's managed egress and secret proxy. This direct-token behavior is specific to managed GitHub App connections. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.