Skip to main content
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 maximum permissions this agent needs, then select the connection with useConnection():
The supported permissions are actions, checks, contents, issues, metadata, and pull_requests. metadata is read-only. Request only what the agent needs. useConnection(github) activates the declared connection for the agent. At session startup, OpenComputer sends the declaration’s exact permissions object when it asks GitHub to mint the installation token. GitHub does not let that token exceed the permissions granted to the App installation. Effective authority is therefore the intersection of:
  • the managed OpenComputer GitHub App’s permission ceiling;
  • the permissions declared in githubApp({ permissions }); and
  • the repositories selected in the attached GitHub installation.

​
Install the App

Deploy the agent, open its project in the OpenComputer dashboard, and choose GitHub. Install the managed OpenComputer GitHub App into a user or organization account. GitHub lets the installer select all repositories or a specific set of repositories. 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.

​
Use Git and the API

Inside the agent sandbox, ordinary GitHub tooling works directly. gh reads the injected GH_TOKEN automatically:
OpenComputer mints a GitHub installation token whose permissions are limited to those declared by the deployed agent. GitHub installation tokens expire after about one hour.

​
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, troubleshooting required permissions, and listing repositories accessible to an installation.
The short-lived token is available inside the eligible agent’s sandbox as GH_TOKEN and GITHUB_TOKEN for the operation. 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.