Connect a GitHub repository to Shipyard

Connecting a repository creates a Shipyard project that watches a branch for pushes. When new commits arrive, the CI engine clones, builds, and deploys your code automatically. This guide walks through each step from OAuth authentication to webhook registration.

Authenticate with GitHub

Navigate to GET /api/auth/github in your browser. Shipyard redirects you to GitHub’s OAuth consent screen requesting the read:user, repo, and read:org scopes. After you approve, GitHub redirects back to the callback endpoint and Shipyard issues a JWT. Store this token — every subsequent API call requires it in the Authorization: Bearer <token> header.

Browse your organizations

Call GET /api/repo/orgs to retrieve a list of your GitHub organizations and personal account. The response includes each account’s login name, which you’ll use to list repositories in the next step.

curl https://your-server/api/repo/orgs \
  -H "Authorization: Bearer <your-jwt>"

List repositories

Call GET /api/repo/repos with the org and page query parameters to paginate through repositories for a given account. Results are sorted by creation date (newest first) and filtered to repos you own.

curl "https://your-server/api/repo/repos?org=yourorg&page=1" \
  -H "Authorization: Bearer <your-jwt>"

Each result includes the repository name, default branch, HTTPS URL, and owner — everything you need to create the project.

Create the project

Send a POST /api/project request with the repository details and any build configuration. Shipyard validates the inputs, registers a webhook on the repo, inserts the project record, and immediately queues an initial build from the latest commit on the configured branch.

curl -X POST https://your-server/api/project \
  -H "Authorization: Bearer <your-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-frontend",
    "repoUrl": "https://github.com/yourorg/my-frontend",
    "branch": "main",
    "installCommand": "npm install",
    "buildCommand": "npm run build",
    "secrets": [
      { "key": "API_URL", "value": "https://api.example.com" }
    ]
  }'

A successful response returns 201 with the project record and the ID of the initial build.

Webhook registered automatically

Shipyard calls the GitHub API on your behalf to register a push-event webhook on the repository. The webhook ID is stored against the project record so Shipyard can remove it if you later delete the project. From this point forward, any push to the configured branch triggers a new build — no manual setup required.

Project fields

Field	Required	Default	Description
`name`	Yes	—	Unique project name. Becomes the subdomain used for deployment.
`repoUrl`	Yes	—	Full HTTPS URL of the GitHub repository.
`branch`	Yes	—	Branch to watch. Pushes to this branch trigger builds.
`installCommand`	No	`npm install`	Command to install dependencies inside the build container.
`buildCommand`	No	—	Command to produce the build output. If omitted, Shipyard skips the Docker build step and deploys static files directly.
`outputDirectory`	No	`./`	Set via `PUT /api/project/projects/:projectId` after creation. Shipyard auto-detects `dist` for Vite and `.next` for Next.js at build time.
`secrets`	No	`[]`	Array of `{ "key": string, "value": string }` pairs. Values are encrypted with AES-256-GCM before storage and decrypted only at build time.

The project name must be unique per user. It becomes the subdomain at which your project is served, for example https://my-frontend.yourdomain.com. Choose a name that is URL-safe and does not conflict with existing projects.

Get Started

Core Concepts

Guides

Security

Connect a GitHub repository to Shipyard

Project fields

​Project fields

Project fields