Built from a repository

Cubeship builds on the box. Two sources, and they differ in where the recipe comes from:

• dockerfile — a Dockerfile in the repository. BuildKit clones and builds; nothing touches the daemon's disk.
• railpack — no Dockerfile. Railpack reads the code, works out the language, the install, the build and the start command, and hands BuildKit a plan.

cubeship app create api --project shop --source dockerfile \
  --repo https://github.com/you/api --ref main --dockerfile deploy/Dockerfile
cubeship app create web --project shop --source railpack \
  --repo https://github.com/you/web

--ref is a branch, a tag or a commit; empty means the repository's default branch. --dockerfile is the path inside the repository; empty means Dockerfile at the root.

The repositoryCopy Anchor Link

It must be https://, http:// or git://. The rule is about what the builder can fetch unaided: SSH needs a key this instance does not have, and a clone failing on a host key deep inside a build explains nothing.

A private repository needs a connected Git provider under Git providers. GitHub uses a GitHub App; Bitbucket, GitLab and Gitea use a token. Credentials are passed to the builder separately from the repository URL and are not stored in a deployment row.

Deploying on pushCopy Anchor Link

Connect a provider under Git providers and pushes to its repositories can build and deploy the app. GitHub and Bitbucket register their hooks during connection. For GitLab and Gitea, add a push webhook in each repository using the URL and secret shown in the connection's Webhook dialog. Select JSON payloads; in Gitea, select the Gitea webhook type.

GitLab.com and self-hosted GitLab instances need a personal access token with read_api and read_repository. Gitea instances need a token with read:user, read:organization and read:repository. Enter the instance's HTTPS base URL and token in Git providers. Cubeship lists repositories the token can access, including Gitea organization repositories. Add the webhook to any repository you want to deploy on push.

For a connected repository:

• An app with no ref deploys on a push to any branch.
• An app with a ref deploys on a push to that branch — naming one is how you opt out of the others.
• A tag is never a branch. Pushing a tag deploys nothing.

For a repository without a connected provider or push webhook, deploy manually:

cubeship app deploy shop/api                # the configured ref
cubeship app deploy shop/api --tag feature  # this branch, this once

The tag argument of a deploy overrides the stored ref, which is how "deploy this branch" works. The deployment records what actually built.

What Railpack readsCopy Anchor Link

A Railpack build reads the app's environment variables, not only the container. Versions and commands a project pins go there:

Two apps on one repository with different environments are two different builds. A repository Railpack cannot plan — no start command it can find, say — fails the deploy with Railpack's own explanation in the deployment's log.

The build logCopy Anchor Link

A build is the one part of a deploy long enough that watching it is the point. Its output is written to the deployment while it runs, capped at 256 KiB keeping the tail — the reason a build failed is at the end of what it printed. Open the deployment on the app's Overview tab.

Where the build happensCopy Anchor Link

Always on the control plane, wherever the app runs. The builder (cubeship-buildkit) starts on the first build and not before: an instance that only runs images it is given never runs a privileged container it does not need.

• An app on this machine gets the image loaded straight into the local Engine. It never leaves the box.
• An app placed on another machine gets it pushed to the instance's registry, and that machine pulls it. So a building app can only be placed elsewhere once the instance has a domain — the registry follows the domain — and is refused with that reason otherwise.

Build caches are per app, in the data directory, and nothing prunes them. docker exec cubeship-buildkit buildctl prune is the manual answer for now.

Who may buildCopy Anchor Link

Running an image somebody already published is a member's job. Turning source into an image is an admin's: a build executes whatever the repository contains, on this host, with the builder's privileges, which is a different kind of act.

That binds three things: creating a building app, deploying one, and writing its environment — because for a Railpack app the environment is build input, and RAILPACK_BUILD_CMD is a command the build runs. Reading stays a member's.