Skip to main content
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.
1

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.
2

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>"
3

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.
4

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.
5

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

FieldRequiredDefaultDescription
nameYes—Unique project name. Becomes the subdomain used for deployment.
repoUrlYes—Full HTTPS URL of the GitHub repository.
branchYes—Branch to watch. Pushes to this branch trigger builds.
installCommandNonpm installCommand to install dependencies inside the build container.
buildCommandNo—Command to produce the build output. If omitted, Shipyard skips the Docker build step and deploys static files directly.
outputDirectoryNo./Set via PUT /api/project/projects/:projectId after creation. Shipyard auto-detects dist for Vite and .next for Next.js at build time.
secretsNo[]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.

Build docs developers (and LLMs) love

Get started for freeTalk to us