> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opencomputer.dev/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 maximum permissions this agent needs, then select the connection
with `useConnection()`:

```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.

`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:

```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
```

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](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).

<Warning>
  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.
</Warning>

Other `defineConnection()` providers continue to use OpenComputer's managed
egress and secret proxy. This direct-token behavior is specific to managed
GitHub App connections.