Git repositories

A Git service builds your repository on every deploy and runs the result. Repositories with a Dockerfile build from it. Repositories without one build through Railpack, which detects the language and framework and creates an image for you.

Create a Git service

Follow the build on the service's Deployments tab. See Deployments and logs.

Public repositories

Any public repository works through its https:// URL, from GitHub, GitLab, Codeberg or any other host:

https://github.com/owner/repository

Harblet clones it without credentials. URLs with a username or password, SSH URLs and other protocols aren't accepted.

Private repositories

Private repositories need a Git connection. Harblet has two kinds:

• GitHub through a GitHub App that Harblet creates for you. The app can only read the repositories you choose.
• GitLab through an access token that you create, on GitLab.com or on a GitLab you host yourself.

Connect GitHub

The connection now shows under Settings → Git. Its Access column shows All repositories or Selected repositories. Click Choose repositories to change them on GitHub.

If you left GitHub before installing the app, the connection shows Not installed. Click Install to finish.

Connect GitLab

The connection shows under Settings → Git with the token's name. Account shows your username for a personal access token, or the group or project for a group or project access token. Access shows when the token expires, with Expires soon in its last 30 days.

Replace a GitLab token

Harblet doesn't renew tokens. Before a token expires, create a new one on GitLab. Then click Replace token next to the connection under Settings → Git, enter the new token and click Replace token.

The services that use the connection keep it, and their next build clones with the new token. The new token needs the same scopes and has to come from the same GitLab.

A token that expired or was revoked shows Expired or revoked. Builds of its private repositories fail until you replace it.

Choose a repository

The Repository field in New service from Git and in a service's Settings lists every repository the Git connections can read, grouped by connection, for example GitHub · acme or GitLab · acme. Private repositories have a lock. Choosing one also sets the branch to the repository's default branch.

To enter a URL instead, click Use a public URL. Click Choose a repository to go back to the list.

A connection that Harblet can't reach shows Unreachable under Settings → Git. Hover over it for the reason.

Remove a connection

Under Settings → Git, click the trash button of the connection, then Remove connection. Services that used it clone without credentials from then on, so builds of private repositories fail.

• GitHub: Harblet uninstalls the app from the account and forgets it. The app itself stays on GitHub. Delete it there in the app's settings under Advanced.
• GitLab: Harblet forgets the token. The token stays valid on GitLab. Revoke it there if nothing else uses it.

How Harblet builds

Every build runs these steps:

1. Clone. Harblet clones the newest commit of the branch. The build output names the commit.
2. Build. Harblet builds the root directory:
   • with the Dockerfile at Dockerfile path, if you set one,
   • otherwise with a Dockerfile in the root directory, if there is one,
   • otherwise with Railpack.
3. Deploy. Harblet stores the image in its own registry and deploys it.

Railpack

Railpack finds out how to build and start your app from its files, for example a package.json, requirements.txt or go.mod. If it can't find a start command, the build fails. Configure Railpack with a railpack.json in the root directory or with environment variables, as described in the Railpack documentation.

Variables during the build

All of the service's environment variables reach the build too:

• Railpack gets them as environment variables and as build secrets.
• Dockerfiles get them as build arguments and as build secrets. Read them with ARG, or mount them as a secret:

ARG NEXT_PUBLIC_API_URL
RUN --mount=type=secret,id=NPM_TOKEN NPM_TOKEN=$(cat /run/secrets/NPM_TOKEN) npm ci

Prefer the secret mount for credentials, since build arguments can end up in the image's history.

The PORT variable

When your Git service has a port, Harblet sets PORT to it while the service runs, unless you set PORT yourself. Make your app listen on PORT. PORT isn't set during the build.

Build limits

• 30 minutes. Builds that take longer fail with "The build took longer than 30 minutes."
• x86_64 and arm64. Railpack builds run on these architectures only.
• The last five builds of each service stay in Harblet's registry. Older builds may no longer be available to redeploy.

Deploy on every push

Harblet doesn't deploy on push by itself yet. Call the service's deploy hook at the end of your CI pipeline instead. The build then takes the newest commit of the branch.

Build errors