Skip to content

Deploying from a repository

velonde git bind ties an app to a branch of a git repository, so that merging into the branch deploys the app. This page covers binding an app, the two kinds of repository URL, and what the workspace does with the repository.

Once an app is bound, the workspace checks the branch once a minute and builds every new head once. Nobody has to run a command or have a session open. The workspace refuses velonde deploy for a bound app.

$ velonde git bind git@github.com:acme/sales.git --branch main
velonde: github.com:22 host key pinned: SHA256:...
velonde: git@github.com:acme/sales.git@main is at 4f2c9a1
velonde: building sales as ...
...
velonde: bound to git@github.com:acme/sales.git@main: a push to the branch deploys within a minute, 'velonde deploy' is off for 'sales'

Two kinds of URL

SSH, written git@host:path or ssh://host/path. The workspace creates a key pair for the binding. The first velonde git bind prints the public key and the fingerprints of the server's host key, then stops. To finish the binding:

  1. Register the key with the repository as a read-only deploy key (GitHub, GitLab, Gitea) or access key (Bitbucket).
  2. Compare the fingerprints with those your forge publishes.
  3. Run the same command again.

You paste nothing into the workspace, and no token can expire. velonde git status shows the key again. velonde git unbind discards it, and the next bind creates a new one.

HTTPS, with a read-only token. Use a project or deploy token of the repository. A personal token stops working when its owner leaves, and the binding breaks with it. Pass the token with --token or in the environment variable VELONDE_GIT_BIND_TOKEN. Without either, the command asks for it in the terminal, which keeps it out of your shell history. Each forge expects its own user name with a token, which you pass with --user: oauth2 for GitLab, x-token-auth for Bitbucket, and any name for GitHub and Azure DevOps. The workspace refuses plain http://. It stores the token only after the first build has succeeded, so a failed bind leaves nothing behind.

Both kinds take these options: --branch (default main), --path for an app in a subdirectory of the repository, and --name to give the app a name other than the repository's. If the velonde.yaml in the repository sets name, the app must have that name, so pass it with --name when it differs from the repository's name.

What the workspace does with the repository

The workspace reads velonde.yaml from the repository, as in any deploy. A committed .Renviron becomes the app's secret, so keep secrets out of the repository and set them with velonde env set instead. The app's directory in the repository has the size limit of an upload: 200 MB compressed. To get it, the workspace clones the latest commit of the whole branch, also for an app in a subdirectory, and refuses a branch that is larger than 1 GB compressed. Keep large data out of the repository.

Nobody watches a build that a push started. When it fails, the workspace mails the app's owner and maintainers the end of the build's output, if the workspace has a mail account and their user ids are mail addresses in the workspace's mail domains. velonde git status <name> shows the repository, the branch head and when the workspace last checked it. It also shows the last build and its result, and for a failed build the end of its output. The workspace builds a failing commit once and tries again only when the branch moves. velonde history lists these deploys as by git, and velonde apps shows the repository next to the app. On a workspace with monitoring, admins also see the build logs in Grafana.

Everything else works as it does for any app: rollback, env, apikey, run and delete. The people who may push to the branch are not maintainers of the app on the workspace. To let them run these commands, list them in velonde.yaml as described in Work on an app as a team.

Everyone who can push to the bound branch decides what runs, and everyone who can see the app can find its repository with velonde clone. Protect the branch on your git server, so that only reviewed merge requests reach it: a protected branch on GitLab, a branch protection rule or ruleset on GitHub. Others can then propose changes on branches of their own, and the merge deploys them.

A push cannot open an app to more people. A commit that sets audience to external or public, or that removes the app's access lists, fails to build with a message that says so. Someone who may deploy the app then confirms the change once: they run velonde git bind again with --confirm-access.

Unbind an app

velonde git unbind <name> removes the binding and its credential. velonde deploy works again, and the app's history stays. To try something out while an app is bound, either push to the branch, or deploy a copy of the directory with another name in its velonde.yaml.