Skip to content
NebulaCtrldocs
Guides

Deploy from Git

Add a Git repository to a project, build it in your cluster on every push to an environment's branch, and deploy it by hand when you need to.

A Git service builds its image inside your cluster from a repository. A push to the branch an environment tracks builds and deploys that environment when its auto-deploy is on. This page covers the build trigger and the choices around it. For the first run from nothing, follow Deploy your first service.

Before you begin

  • A project with an environment that has a bound cluster. See Connect a cluster.
  • A Git connection that can read the repository, for a private repository or for pushes to trigger builds. See Git providers and registries. A public repository needs no connection, but it builds only when you start it.
  • A repository with a Dockerfile, or a project that Railpack recognizes. See Build without a Dockerfile.
  • The deployer role or higher to add a service and deploy it. Changing an environment's branch, and creating a project, need the admin role.

Add the repository

  1. Open the project. Right-click the canvas and select New service…, or press N.
  2. In Add to canvas, select Git repository.
  3. Pick the connection, if you have more than one, and the repository.
  4. Select Add repository.

NebulaCtrl adds a web service named after the repository that builds its Dockerfile, with the build context ., on port 8080. If the repository's nebula.toml defines processes, they replace that default. Change the port and the processes later from the service's Settings tab. The first deploy builds the repository's default branch.

With a cluster bound to the environment, a service added from Add repository, Create service or a new project's Create with Dockerfile only is created and its first deploy is staged. Nothing builds until you apply the staged change set. In the staged bar, select Deploy N changes, or Request approval on a protected environment. See Change sets and approvals.

Choose the branch and auto-deploy

Each environment tracks one branch and has an Auto-deploy setting. A push to the tracked branch builds the service in that environment only when auto-deploy is on. With it off, a push builds nothing there, and you deploy by hand.

  1. Open the environment's menu and select Environment settings….
  2. Under Deploys, set Branch, the branch whose pushes build and deploy here.
  3. Turn Auto-deploy on or off, and select Save.

A service can override the environment's auto-deploy. Open the service's Settings tab and use its Auto-deploy switch, which stages into the change set like other per-environment settings. The switch is available for Git services and for image services with a push trigger. It is not available for a public repository, because a public repository has no webhook.

One push can build in several environments: every environment that tracks the pushed branch with auto-deploy on gets its own build.

Deploy on a push

  1. Push a commit to the tracked branch.
  2. The webhook of your Git provider tells NebulaCtrl. Branch deletions and pushes to a tag are ignored.
  3. For each matching service and environment, NebulaCtrl queues a build of the pushed commit. A newer push supersedes every older queued or running build of the same service and environment, and cancels one that is running.
  4. The build runs as a job in the cluster. A cluster runs at most two builds at a time, and a build that runs longer than 30 minutes fails.
  5. A successful build creates a release the way a manual deploy does. A protected environment waits for an approval.

Builds appear as rows in the service's Deployments tab, labeled Queued, Building, Built, Build failed, Cancelled, Superseded or Built · not deployed. A row from a push shows push as its actor. The image is tagged with the first 12 characters of the commit.

For a connected repository, NebulaCtrl reports the build and the deployment on the commit as the status nebulactrl/ENVIRONMENT, linked to the service's Deployments tab. A public repository reports nothing.

Verify

Push a change. In Deployments, a build row appears and moves from Queued to Building to Built, and a new release takes over once it is healthy. The status on the commit changes to Deployment is healthy.

Deploy by hand

Select Deploy in the service's header. For a Git service this builds the head of the environment's tracked branch and deploys it as soon as the build succeeds. In a protected environment the release may wait in Approvals.

To build another branch, select the caret beside Deploy and choose Deploy a different branch…. For a connected repository, pick a Branch. For a public repository, enter a Branch, tag, or commit, which NebulaCtrl resolves anonymously at build time. Select Build and deploy.

A public repository can deploy only this way: it has no webhook, so a push never starts a build.

Retry or cancel a build

In Deployments, a failed build at the top shows Retry, and the service's header shows Retry build. Either builds the same commit again, not the new head of the branch. A queued or running build shows Cancel, and you confirm with Cancel build. A build that fails writes its reason to the build log: open the row to read it. Common causes are listed in Builds.

Next steps

Glossary

Definitions of the terms NebulaCtrl uses in the console, the API and these docs, each linked to the page that explains it.

Deploy a container image

Run an image from a public or private registry as a service, deploy new tags and digests, and trigger a deploy from a Git push.

On this page

Before you beginAdd the repositoryChoose the branch and auto-deployDeploy on a pushVerifyDeploy by handRetry or cancel a buildNext steps