# How to Integrate Openship with GitHub for Git-Based Deployments

> Integrate Openship with GitHub for Git-based deployments. Link your repository, configure authentication, and enable webhooks for automatic deployments on every push.

- Repository: [oblien/openship](https://github.com/oblien/openship)
- Tags: how-to-guide
- Published: 2026-07-21

---

**To integrate Openship with GitHub, link a repository to your project to store the owner/repo pair in the database, configure authentication via GitHub App installation, PAT, or deploy keys, and optionally enable webhooks for automatic deployments on every push.**

Openship treats GitHub repositories as first-class deployment sources, enabling automated git-based deployments through a flexible authentication system. When you integrate Openship with GitHub, the platform stores repository metadata in the project schema and manages credentials securely to clone private repos. This guide explains the authentication flows, webhook configuration, and build pipeline execution based on the oblien/openship source code.

## Authentication and Credential Management

Openship supports three authentication methods to access GitHub repositories, all converging in the `assembleGitClone` function in [`packages/adapters/src/runtime/git-clone.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/runtime/git-clone.ts).

### GitHub App Installation

The recommended approach uses a GitHub App installation. When you install the Openship GitHub App, the platform saves the `installationId` in the `project.installationId` field defined in [`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/project.ts). The token resolver in [`packages/db/src/repos/git-installation.repo.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/repos/git-installation.repo.ts) exchanges this ID for a temporary access token with repository permissions.

### Personal Access Tokens (PAT)

For individual users, you can provide a Personal Access Token with `repo` scope. The system encrypts and stores this in `settings.gitHubPat` according to [`packages/db/src/schema/settings.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/settings.ts). During cloning, `assembleGitClone` injects the token into the HTTPS URL format: `https://x-access-token:<token>@github.com/...`.

### SSH Deploy Keys

For server-side operations, Openship generates unique SSH deploy keys per server. These are stored in [`packages/db/src/schema/server-github.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/server-github.ts) and tracked via [`github_deploy_key.repo.ts`](https://github.com/oblien/openship/blob/main/github_deploy_key.repo.ts). The clone builder constructs SSH URLs (`git@github.com:owner/repo.git`) and sets `GIT_SSH_COMMAND` to use the specific private key.

### The Clone Builder Logic

Regardless of the authentication method, the `assembleGitClone(auth)` function returns a `GitCloneInvocation` object containing:

- `cloneUrl`: The authenticated URL for `git clone`
- `gitEnv`: Environment variables like `GIT_SSH_COMMAND` or `GIT_TERMINAL_PROMPT`
- `credFlag`: Optional credential helper configuration for token-based clones

The function prioritizes SSH deploy keys, falling back to credential helpers or embedded tokens based on availability.

## Project Source Configuration

Projects define their GitHub source using the `ProjectSource` interface in [`packages/core/src/project-source.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/project-source.ts):

```ts
interface GitHubSource {
  mode: "github";
  owner: string;
  repo: string;
  ref?: string; // branch, tag, or commit SHA
}

```

When you run `openship init`, the CLI parses your repository URL into owner and repo components, then stores this configuration in the database. The optional `ref` parameter allows pinning to specific branches, tags, or commit SHAs.

## Webhook Registration for Push-to-Deploy

To enable automatic deployments, Openship registers a GitHub webhook using the installation token. The webhook ID and signing secret are persisted in `project.githubWebhookId` and `project.githubWebhookSecret` as defined in the project schema.

Incoming push events are processed by the webhook handler in [`packages/db/src/schema/github-webhook-event.repo.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/github-webhook-event.repo.ts), which creates a new `Deployment` row to trigger the build pipeline.

## Build Pipeline Execution

During deployment, the pipeline executes the clone operation through the shared executor. The process follows these steps:

1. Resolve credentials using the most privileged available method
2. Call `assembleGitClone` to build the git command
3. Execute the clone with appropriate environment variables
4. Stream stdout to the dashboard for real-time logs

The docker build context in [`packages/adapters/src/runtime/docker-build-context.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/runtime/docker-build-context.ts) serves as the primary entry point that invokes this clone logic.

## Step-by-Step Integration Guide

Follow these steps to integrate Openship with GitHub:

1. **Create a GitHub repository** (public or private) for your application code.

2. **Install the Openship GitHub App** on your account or organization. The installation ID automatically saves to your project record.

3. **Initialize the project** locally:

   ```bash
   openship init
   ```

   When prompted, enter your repository URL (e.g., `https://github.com/your-org/awesome-service.git`).

4. **Configure authentication** (if not using the GitHub App):

   ```bash
   export OPENSHIP_GITHUB_PAT=ghp_XXXXXXXXXXXXXXXXXXXX
   ```

   Or set the PAT in the dashboard under Settings.

5. **Enable push-to-deploy** via the API:

   ```http
   POST /api/projects/:projectId/webhooks
   Content-Type: application/json

   {
     "enablePushDeploy": true
   }
   ```

6. **Deploy manually** or push to your default branch to trigger automatic deployment:

   ```bash
   openship deploy
   ```

## Summary

- Openship stores GitHub repository metadata in [`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/project.ts) using the `ProjectSource` interface with `mode: "github"`.
- Three authentication methods are supported: GitHub App installations (preferred), Personal Access Tokens, and SSH deploy keys, all handled by `assembleGitClone` in [`packages/adapters/src/runtime/git-clone.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/runtime/git-clone.ts).
- Webhook registration enables push-to-deploy functionality by storing webhook IDs and secrets in the project record and processing events through [`github-webhook-event.repo.ts`](https://github.com/oblien/openship/blob/main/github-webhook-event.repo.ts).
- The build pipeline uses a shared executor to run git clone commands with the appropriate credentials and environment variables.

## Frequently Asked Questions

### How does Openship authenticate with private GitHub repositories?

Openship authenticates with private repositories using one of three methods: GitHub App installations stored in `project.installationId`, Personal Access Tokens encrypted in `settings.gitHubPat`, or SSH deploy keys tracked in `server_github` and `github_deploy_key` tables. The `assembleGitClone` function in [`packages/adapters/src/runtime/git-clone.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/runtime/git-clone.ts) automatically selects the most secure available credential and constructs the appropriate clone URL and environment variables.

### What triggers an automatic deployment in Openship?

Automatic deployments trigger when GitHub sends a push webhook event to your Openship instance. When you enable push-to-deploy, Openship registers a webhook on your repository and stores the webhook ID and secret in `project.githubWebhookId` and `project.githubWebhookSecret`. The webhook handler in [`packages/db/src/schema/github-webhook-event.repo.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/github-webhook-event.repo.ts) processes these events and creates a new deployment record, initiating the build pipeline without manual intervention.

### Can I deploy a specific branch or commit instead of the default branch?

Yes. The `ProjectSource` interface in [`packages/core/src/project-source.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/project-source.ts) includes an optional `ref` field that accepts branch names, tags, or commit SHAs. When initializing your project with `openship init`, you can specify a reference, or update the project configuration via the API to pin deployments to specific versions of your codebase.

### Where does Openship store GitHub credentials securely?

GitHub App installation IDs are stored in the `project` table ([`packages/db/src/schema/project.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/project.ts)), Personal Access Tokens are encrypted in the `settings` table ([`packages/db/src/schema/settings.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/settings.ts)), and SSH deploy keys are maintained in `server_github` ([`packages/db/src/schema/server-github.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/schema/server-github.ts)) with their GitHub API references tracked separately. The token resolver in [`packages/db/src/repos/git-installation.repo.ts`](https://github.com/oblien/openship/blob/main/packages/db/src/repos/git-installation.repo.ts) handles the exchange of installation IDs for temporary access tokens at runtime.