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

# Git Deployment

> Connect repositories and manage git-based deployments.

Connect a Git repository to a pod for automatic or manual deployments. Supports GitHub (with webhooks and commit status checks) and any Git URL via HTTPS.

## Get Git Config

```
GET /api/pods/{name}/git
```

**Response: `200 OK`**

```json theme={null}
{
  "repo_url": "https://github.com/you/repo",
  "branch": "main",
  "auto_deploy": true,
  "build_command": "",
  "last_deployment": {
    "id": "deploy_abc123",
    "status": "success",
    "commit_sha": "a1b2c3d",
    "commit_message": "fix: update error handling",
    "created_at": "2026-02-20T10:30:00Z",
    "finished_at": "2026-02-20T10:30:18Z"
  },
  "created_at": "2026-02-20T09:00:00Z"
}
```

Returns `null` if no repository is connected.

## Connect a Repository

```
POST /api/pods/{name}/git
```

**Request Body:**

```json theme={null}
{
  "repo_url": "https://github.com/you/repo",
  "branch": "main",
  "auth_token": "ghp_optional_for_private_repos",
  "build_command": "",
  "auto_deploy": true
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `repo_url` | string | Yes | Git repository URL (HTTPS) |
| `branch` | string | No | Branch to deploy (default: `main`) |
| `auth_token` | string | No | Personal access token for private repos |
| `build_command` | string | No | Custom build command (overrides auto-detection) |
| `auto_deploy` | boolean | No | Deploy on push (default: `true`) |

**Response: `201 Created`**

Returns the git config object.

**Errors:**

| Code | Reason |
| - | - |
| `400` | Invalid URL, pod not running |
| `409` | Repository already connected |

## Update Settings

```
PUT /api/pods/{name}/git
```

**Request Body:**

```json theme={null}
{
  "branch": "develop",
  "install_command": "npm ci",
  "build_command": "npm run build",
  "start_command": "node server.js",
  "release_command": "npx prisma migrate deploy",
  "subdirectory": "apps/web",
  "auto_deploy": false
}
```

All fields are optional. Only provided fields are updated; send `""` to clear one and fall back to
auto-detection.

| Field | Description |
| - | - |
| `branch` | Branch to deploy from |
| `install_command` | Dependency install, run first |
| `build_command` | Build, run after install |
| `start_command` | The long-running process that serves the app |
| `release_command` | One-shot command run after build and after managed services are wired, on **every** deploy - your database migration. A failing release command fails the deploy |
| `subdirectory` | Path within the repo to deploy, for monorepos |
| `auto_deploy` | Whether a push to the branch triggers a deploy |

**Response: `200 OK`**

## Disconnect

```
DELETE /api/pods/{name}/git
```

**Response: `200 OK`**

```json theme={null}
{
  "status": "disconnected"
}
```

## Trigger Deploy

```
POST /api/pods/{name}/git/deploy
```

No request body required. Pulls the latest code from the configured branch and deploys.

**Response: `202 Accepted`**

```json theme={null}
{
  "id": "deploy_xyz789",
  "status": "deploying",
  "created_at": "2026-02-20T11:00:00Z"
}
```

Deployment runs asynchronously. Poll the deployment detail endpoint to check status.

## List Deployments

```
GET /api/pods/{name}/git/deployments
```

| Query Param | Type | Default | Description |
| - | - | - | - |
| `limit` | int | 10 | Max deployments to return |

**Response: `200 OK`**

```json theme={null}
{
  "deployments": [
    {
      "id": "deploy_abc123",
      "status": "success",
      "commit_sha": "a1b2c3d",
      "commit_message": "fix: update error handling",
      "trigger": "push",
      "created_at": "2026-02-20T10:30:00Z",
      "finished_at": "2026-02-20T10:30:18Z"
    }
  ]
}
```

**Deployment statuses:** `deploying`, `success`, `failed`, `rolled_back`

**Trigger types:** `push` (webhook), `manual`, `rollback`

## Get Deployment Detail

```
GET /api/pods/{name}/git/deployments/{deployId}
```

**Response: `200 OK`**

Returns a single deployment object with a `build_log` field containing the full build output:

```json theme={null}
{
  "id": "deploy_abc123",
  "status": "success",
  "commit_sha": "a1b2c3d",
  "commit_message": "fix: update error handling",
  "trigger": "push",
  "build_log": "Pulling latest code...\nnpm install...\nnpm run build...\nRestarting service...\nDeploy complete.",
  "created_at": "2026-02-20T10:30:00Z",
  "finished_at": "2026-02-20T10:30:18Z"
}
```

## Rollback

```
POST /api/pods/{name}/git/rollback
```

**Request Body:**

```json theme={null}
{
  "deployment_id": "deploy_abc123"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `deployment_id` | string | No | Target deployment ID (defaults to previous deployment) |

**Response: `202 Accepted`**

Returns a new deployment object with `trigger: "rollback"`.

## Webhooks

These endpoints are public (no auth required). They receive push events from Git providers.

```
POST /api/webhooks/github
POST /api/webhooks/git/{podName}
```

The GitHub webhook is configured automatically when connecting a GitHub repository. For other providers, use the generic webhook URL shown in the dashboard.

Commits containing `[skip deploy]` in the message are ignored.

### Repair Auto-Deploy

```
POST /api/pods/{name}/git/webhook
```

Re-creates the push webhook for a pod whose auto-deploy has stopped firing. Use it when the pod is
connected to a repository, auto-deploy is on, but pushes no longer trigger a build - usually because
the repository was connected with a token rather than through the GitHub App, and the webhook was
deleted or never created.

No request body. A pod already deploying through the GitHub App is a no-op.

**Response: `200 OK`**

```json theme={null}
{
  "config": { "repo_url": "https://github.com/you/my-api", "auto_deploy": true }
}
```

If the webhook can't be created for you - you need admin rights on the repository - the response is
still `200`, but carries an `error` field alongside the config, and the config now contains a
webhook secret so you can add the hook by hand:

```json theme={null}
{
  "config": { "...": "..." },
  "error": "could not create the webhook automatically - add it manually with the URL and secret below (you need admin rights on the repository)"
}
```

Returns `404` if the pod has no repository connected.

## GitHub App

The InstaPods GitHub App is what lets you browse and deploy private repositories without pasting a
token. These endpoints back the GitHub card on **Dashboard → Integrations**. All require
authentication.

### List Installations

```
GET /api/github/installations
```

**Response: `200 OK`**

```json theme={null}
{
  "installations": [
    {
      "id": 12345678,
      "account": "your-org",
      "account_type": "Organization",
      "avatar_url": "https://avatars.githubusercontent.com/...",
      "repository_selection": "selected",
      "html_url": "https://github.com/organizations/your-org/settings/installations/12345678"
    }
  ],
  "configured": true,
  "requires_github_link": false,
  "connection": {
    "login": "you",
    "avatar_url": "https://avatars.githubusercontent.com/...",
    "email": "you@example.com",
    "connected_at": "2026-02-01T10:00:00Z"
  },
  "app_install_url": "https://github.com/apps/instapods/installations/new"
}
```

An empty `installations` list means different things depending on the flags, which is why they're
there:

| Field | Meaning when set |
| - | - |
| `configured` | Whether the GitHub App is wired up at all. `false` means we couldn't ask GitHub, not that you have no installations |
| `requires_github_link` | You have no linked GitHub identity (you signed up with Google or email). Sign in with GitHub before installing the App |
| `connection` | The GitHub account you're linked as. Absent when the link is missing or expired |
| `app_install_url` | Where to send someone who has no installation yet |

### List Repositories in an Installation

```
GET /api/github/installations/{installationId}/repos
```

Returns the repositories that installation can see.

<Tip>
  An installation whose `repository_selection` is `selected` only exposes the repos you ticked when
  installing the App. That is far and away the most common reason this list comes back empty or
  missing the repo you wanted; fix it at the installation's `html_url` on GitHub.
</Tip>

| Code | Reason |
| - | - |
| `400` | GitHub App not configured, or the installation ID isn't a number |
| `403` | Your GitHub account isn't linked, or that installation isn't one you can access |

### Create a Repository

```
POST /api/github/repos
```

Creates a new repository on your GitHub account. Used by the dashboard when you want a pod's code
pushed somewhere it can auto-deploy from.

```json theme={null}
{
  "name": "my-api",
  "description": "API for my app",
  "private": true
}
```

**Response: `201 Created`** - returns the created repository. Returns `400` if `name` is missing or
your GitHub account isn't linked.


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