Skip to content
Avaloi

Connect GitHub, GitLab, or Bitbucket

Make a GitHub, GitLab, Bitbucket, or other Git repository the source of a staging environment's code, with a read only deploy key and a webhook.

You can keep your code on GitHub, GitLab, Bitbucket, or any Git host and let Avaloi pull it into staging or a multidev. Avaloi uses a deploy key, so it never needs your GitHub password or access to your other repositories.

Before you start

  • Pick the environment in the top bar (staging or a multidev) and open Info.
  • The environment must be in Git mode. On the Connection mode card, click Switch to Git mode. If staging has uncommitted changes, commit them first.
  • Live never connects. Code reaches live only by a promote from staging.

1. Add the deploy key

On the Connect an external repository card, click Show deploy key and copy it. Avaloi makes one key for the site and keeps the private half to itself.

GitHub: open the repository, then Settings, Deploy keys, Add deploy key. Name it Avaloi, paste the key, leave Allow write access off, and click Add key.

GitLab: Settings, Repository, Deploy keys. Paste the key and leave write access off.

Bitbucket: Repository settings, Access keys, Add key.

2. Connect the repository

Enter the SSH address of the repository, such as [email protected]:acme/site.git, and the branch, such as main. Click Connect repository.

Avaloi shows a webhook URL and a secret. Copy the secret now: Avaloi shows it only once.

For GitHub, GitLab, and Bitbucket, Avaloi already knows the host's SSH key. For another host, the card asks for a Host key: paste the host's known_hosts line (run ssh-keyscan your.git.host to get it). Through the API you can send "host_key_policy": "accept_first" instead, and Avaloi records the key it sees on the first pull and refuses any other key after that.

3. Add the webhook

GitHub: Settings, Webhooks, Add webhook. Payload URL: the webhook URL. Content type: application/json. Secret: the secret. Events: Just the push event.

GitLab: Settings, Webhooks. URL: the webhook URL. Secret token: the secret. Trigger: Push events.

Bitbucket: Repository settings, Webhooks, Add webhook. URL: the webhook URL. Secret: the secret. Trigger: Repository push.

4. Pull

Avaloi pulls once right after you connect, to check the key works. After that, every push to the branch pulls by itself. Click Pull now at any time.

Each pull is a job you can follow under Jobs. Avaloi builds the new commit and switches the environment to it.

When a pull fails

The card says What to do
The Git host refused Avaloi's deploy key Add the deploy key to the repository (step 1), then click Pull now
Not a fast forward The branch on your Git host does not contain the commit the environment runs. This happens on the first connect of a repository with its own history. Click Replace with the remote branch. Avaloi keeps the old commit
The host key changed Your Git host shows a different SSH key than before. If the host really changed it, connect again
Could not find the repository or branch Check the address and the branch name

While connected

  • Pushes to Avaloi Git for this environment are refused, so there is one source of truth. Push to your Git host instead.
  • SFTP mode is off. Disconnect first if you want to edit files on staging.
  • New webhook secret makes a new secret and stops the old one at once. Update the webhook on your Git host.
  • Disconnect stops the pulls. The code stays as it is.

Build in CI instead

If you build your site in CI (for example, Composer or npm steps), push the built commit to the Avaloi Git remote from your CI job instead of connecting a repository. See Git access.

Not yet

  • A ready made GitHub Action (avaloi/deploy-action) is written but not published on GitHub Marketplace yet.

API

  • POST /v1/sites/{id}/git/deploy-key
  • PUT /v1/environments/{id}/git/connection with {"remote_url": "[email protected]:acme/site.git", "branch": "main", "confirm": true}
  • POST /v1/environments/{id}/git/pull, with {"replace": true, "confirm": true} to replace the branch
  • POST /v1/environments/{id}/git/webhook-secret and DELETE /v1/environments/{id}/git/connection?confirm=true
  • Webhook receiver: POST /hooks/git/{connection_id} (GitHub and Bitbucket sign with HMAC SHA-256, GitLab sends the secret as a token)

Still stuck?

Email [email protected] with your site name and what you tried, or send us a message.