---
title: How to Connect GitHub to a Harness Runtime Session (public)
description: Connect a team GitHub account with OAuth so a session can clone, commit, and open pull requests.
product: Managed Agents
url: https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/connect-github/
last_updated: "2026-09-21"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document).

# How to Connect GitHub to a Harness Runtime Session (public)

DigitalOcean Harness Runtime combines the functionality of a lightweight microVM, built-in tools like chromium and a coding sandbox needed by agents to do work. The product offers rich lifecycle APIs that persist conversational history and working state across sessions, with pause/resume/fork semantics so that developers can control costs and adapt workflows to the nonlinear quirks of agentic work. See [What You Can Build](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/details/what-you-can-build/index.html.md) for example use cases.

Sandboxes have no repository access by default. Connect your team’s GitHub account once, then declare an OAuth secret in the environment spec so hosted sessions can run authenticated `git clone`, `git pull`, and `git push` against private repositories without pasting a personal access token into the spec.

GitHub OAuth is team-scoped. Your team keeps a single GitHub connection, and every session in the team uses that connection. Use a dedicated GitHub team account for it. Running the `connect` command again replaces the existing connection.

## Connect the Team to GitHub

Authorize GitHub from `doctl`. This is a one-time step per team:

```shell
doctl harness-runtime auth github
```

This starts a browser-based authorization:

1. `doctl` prints an authorization URL and opens it.
2. Approve access in the browser.
3. `doctl` waits and reports **connected** when authorization completes.

Connect before you create the session that declares `GITHUB_TOKEN: oauth/github`. Sessions created before the team connected do not receive the token.

## Declare the OAuth Credential in the Environment Spec

Add a `secrets` field with `oauth/github` when you create the session. The field name is the environment variable the token appears as inside the sandbox.

```yaml
name: my-first-agent
agent: codex
size: mars-2vcpu-4gb
persistent_workspace: true
repos:
  - <your-org>/<your-private-repo>
env:
  MODEL: gpt-5.4
secrets:
  OPENAI_API_KEY: ${OPENAI_API_KEY}
  GITHUB_TOKEN: oauth/github
permissions:
  default: ask
```

**Warning**:

  Declare the GitHub credential under `secrets`. Do not put tokens in `env`. DigitalOcean brokers the OAuth token server-side when the session is created and never persists it as plaintext in the stored spec.

## Run a Repository Workflow

Attach to the session and ask the agent to perform the GitHub workflow you need. For example:

```text
Clone the private repo github.com/<owner>/<repo> using the GITHUB_TOKEN from your env. Create a new branch, update README.md with a Hello World section, commit, push the branch, and open a pull request against main. Share the PR link when done.
```

Approve the clone and push prompts as they appear.

If the session was created before the team connected, the sandbox does not have `GITHUB_TOKEN`. Create a new session after connecting.

## Use a Personal Access Token

If you prefer a token you manage yourself, create one at [GitHub personal access tokens](https://github.com/settings/tokens/new) with the `repo` scope (or a fine-grained token with `Contents: Read` and the write permissions you need). Then declare it under `secrets`:

```yaml
repos:
  - <owner>/<repo>
secrets:
  GITHUB_TOKEN: ${GITHUB_TOKEN}
```

Export the token in your shell so `doctl` can expand `${GITHUB_TOKEN}` before upload:

```shell
export GITHUB_TOKEN=<your-github-pat>
```