How to Integrate Openship with GitHub for Git-Based Deployments

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.

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. The token resolver in 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. 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 and tracked via 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:

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

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

   export OPENSHIP_GITHUB_PAT=ghp_XXXXXXXXXXXXXXXXXXXX

   Or set the PAT in the dashboard under Settings.

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

   POST /api/projects/:projectId/webhooks
   Content-Type: application/json
   
   {
     "enablePushDeploy": true
   }

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

   openship deploy

Summary

• Openship stores GitHub repository metadata in 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.
• 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.
• 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 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 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 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), Personal Access Tokens are encrypted in the settings table (packages/db/src/schema/settings.ts), and SSH deploy keys are maintained in server_github (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 handles the exchange of installation IDs for temporary access tokens at runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}