> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nasiko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub API

> Connect a GitHub account, list repositories, and build and deploy an agent from a repository.

These routes connect your GitHub account to Nasiko, so you can deploy an agent straight from a repository. The dashboard's **Add Agent** → **Import from GitHub** flow and `nasiko github` call them. They aren't in the generated OpenAPI spec. CLI: [Integration commands](https://docs.nasiko.com/reference/cli/integrations.md#github).

## Before you start

The server operator must register a GitHub OAuth app and set `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`. Without them, most routes return `503` with:

```
GitHub OAuth is not configured on this server (set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET)
```

Check first with [`GET /api/auth/github/status`](#check-whether-github-is-configured), which needs no sign-in.

## Authentication

Every route except `GET /api/auth/github/status` takes a session JWT in `Authorization: Bearer <token>` (from `POST /api/auth/login`) or the dashboard cookie. A missing or expired token returns `401`.

Your GitHub token is stored encrypted, per user, and is never returned by any route. Error bodies are plain text unless a JSON body is shown.

## Check whether GitHub is configured

`GET /api/auth/github/status`

Public. Tells a client whether to offer GitHub at all.

```bash theme={null}
curl https://nasiko.example.com/api/auth/github/status
```

**Response** `200 OK`

```json theme={null}
{ "configured": true }
```

## Connect your GitHub account

`GET /api/github/login`

Returns the GitHub authorization URL for your account. Open it in a browser. Matches `nasiko github connect`.

```bash theme={null}
curl https://nasiko.example.com/api/github/login \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{ "auth_url": "https://github.com/login/oauth/authorize?client_id=Iv1.0123456789abcdef&state=..." }
```

After you approve the app, GitHub sends your browser to `/api/auth/github/callback` on your Nasiko server. Nasiko stores the token and redirects you back to the dashboard. The authorization URL is good for one use, within 10 minutes.

A GitHub account can be linked to only one Nasiko user. Connecting an account that's already linked to someone else fails with `409` on the callback.

**Errors**

| Status | Body |
| - | - |
| `503` | `{ "error": "GitHub OAuth is not configured on this server (...)" }` |
| `500` | `{ "error": "failed to generate authorization URL" }` |

## Check your connection

`GET /api/github/user`

Whether your account is connected, and whether GitHub still accepts the stored token. The dashboard uses it to show the connected account.

**Response** `200 OK`

```json theme={null}
{ "connected": true, "valid": true, "login": "octocat" }
```

| Body | Meaning |
| - | - |
| `{ "connected": true, "valid": true, "login": "..." }` | Connected, and GitHub accepts the token |
| `{ "connected": true, "valid": false, "login": "..." }` | Connected, but the token was revoked or expired. Connect again |
| `{ "connected": false, "valid": false }` | No account connected |
| `{ "connected": false, "configured": false }` | GitHub isn't configured on this server |

## Check your token

`GET /api/auth/github/token`

The same check, in the shape `nasiko github status` reads. It never returns the token itself.

**Response** `200 OK` when connected:

```json theme={null}
{ "success": true, "message": "GitHub token is valid", "status": "connected", "username": "octocat" }
```

| Status | `status` field | Meaning |
| - | - | - |
| `200` | `connected` | GitHub accepts the token |
| `200` | `invalid` | The token is invalid or expired. `success` is `false` |
| `202` | `disconnected` | No account connected. `message` is `GitHub not connected` |
| `503` | `disconnected` | GitHub isn't configured on this server |

## List repositories

`GET /api/github/repositories`

The repositories your GitHub account can access. Matches `nasiko github repos`.

```bash theme={null}
curl https://nasiko.example.com/api/github/repositories \
  -H "Authorization: Bearer $NASIKO_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{
  "repositories": [
    {
      "id": 1296269,
      "name": "support-bot",
      "full_name": "octocat/support-bot",
      "description": "Customer support agent",
      "private": true,
      "clone_url": "https://github.com/octocat/support-bot.git",
      "ssh_url": "git@github.com:octocat/support-bot.git",
      "html_url": "https://github.com/octocat/support-bot",
      "default_branch": "main",
      "updated_at": "2026-11-10T17:02:44Z"
    }
  ],
  "total": 1
}
```

**Errors**

| Status | When |
| - | - |
| `403` | No GitHub account connected |
| `502` | GitHub returned an error |
| `503` | GitHub isn't configured on this server |

## Clone and deploy a repository

`POST /api/github/clone`

Builds an agent from a repository and deploys it. Matches `nasiko github clone` and the dashboard's **Import from GitHub**. The build runs in the background, so the request returns `202` right away.

If you already have an agent with the same name, it's rebuilt and redeployed in place.

**Request body**

| Field | Type | Required | Description |
| - | - | - | - |
| `repository_full_name` | string | Yes | `owner/repo` |
| `branch` | string | No | Branch to build. Default `main` |
| `agent_name` | string | No | Agent name. Default: the repository name. 1 to 128 characters of `a-z`, `A-Z`, `0-9`, `.`, `_`, and `-`, starting with a letter, digit, or `_` |
| `version_override` | string | No | Version to record, as `x.y.z`, for example `1.2.3` |
| `parking_policy` | string | No | `auto` (park the agent when idle) or `resident` (keep it running) |

```bash theme={null}
curl -X POST https://nasiko.example.com/api/github/clone \
  -H "Authorization: Bearer $NASIKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repository_full_name": "octocat/support-bot",
    "branch": "main",
    "agent_name": "support-bot",
    "parking_policy": "auto"
  }'
```

**Response** `202 Accepted`

```json theme={null}
{
  "success": true,
  "message": "Agent 'support-bot' clone queued",
  "agent_name": "support-bot",
  "upload_id": "5b0e8c2a-7d41-4f3a-9b6e-2c1d0a9f8e7b"
}
```

`success: true` means the build was queued, not that it finished. `upload_id` is the build ID. Follow it with any of these:

* `GET /api/agents/deploys/{upload_id}/stream` streams status changes until the build succeeds or fails. The CLI and dashboard use this.
* `GET /api/agents/uploads/{upload_id}` returns the upload's current status.
* [`GET /api/builds/{upload_id}`](https://docs.nasiko.com/api-reference/agent-runtime#get-a-build) and [`GET /api/builds/{upload_id}/logs`](https://docs.nasiko.com/api-reference/agent-runtime#build-logs) return the build and its output.

**Errors**

| Status | When |
| - | - |
| `400` | `parking_policy` isn't `auto` or `resident`, or `agent_name` is invalid |
| `403` | No GitHub account connected |
| `409` | The name belongs to a harness agent, which Nasiko manages |
| `422` | `repository_full_name` or `branch` is malformed, or `version_override` isn't `x.y.z` |
| `503` | GitHub isn't configured on this server |

A server can also refuse a new agent with its own status and body, for example when a plan's agent limit is reached.

## Disconnect your GitHub account

`DELETE /api/github/logout`

Deletes your stored GitHub token from Nasiko. Matches `nasiko github disconnect`. Agents you already built from GitHub keep running. To revoke the app's access on GitHub's side too, remove it in your GitHub settings.

**Response** `200 OK`

```json theme={null}
{ "message": "GitHub credentials cleared" }
```

Disconnecting when no account is connected also returns `200`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.