GitHub App connections

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:

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:

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:

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 <id|account>; 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:

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:

GET /projects/<project-id>/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.

{
  "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:

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, troubleshooting required permissions, and listing repositories accessible to an 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.

Getting started

Concepts

Build an application

Agent API

Test and operate

Examples

Declare access

Install the App

List the repositories an environment can reach

Use Git and the API

Understand GitHub permission responses

​Declare access

​Install the App

​List the repositories an environment can reach

​Use Git and the API

​Understand GitHub permission responses

Declare access

Install the App

List the repositories an environment can reach

Use Git and the API

Understand GitHub permission responses