Skip to main content

Continuous Deployment with GitHub Actions

Use GitHub Actions to build and publish an image from your private GitHub repository, then use the vicu CLI to ask Vicugna to restart the service. On restart, Vicugna pulls the service's configured image again, so a service configured with the latest tag picks up the image just published by the workflow.

Before you begin​

Create the service in Vicugna before enabling this workflow. The workflow restarts an existing service; it does not create one. If you have not yet built and published an image or created the service, Deploy from a private GitHub repository describes one way to do that. Otherwise, use your existing service and make sure it has the private GHCR pull credentials and image reference configured.

The service's configured image must use the same image name and tag that this workflow publishes. The example below publishes ghcr.io/OWNER/REPOSITORY:latest on pushes to main.

Configure GitHub credentials and IDs​

In the GitHub repository, open Settings → Secrets and variables → Actions and add:

  • Repository secret VICUGNA_API_KEY: a Vicugna project API key with access to the project containing the service.
  • Repository variable VICUGNA_PROJECT_ID: the ID of the Vicugna project containing the service.
  • Repository variable VICUGNA_SERVICE_ID: the ID of the service to restart.

Find the project ID in the projects table and the service ID in the services table. The API key is sent as a bearer token by vicu; do not put it in workflow arguments or commit it to the repository. The private GHCR pull token configured on the Vicugna service is separate from this API key and from GitHub Actions' GITHUB_TOKEN.

Set up the workflow​

If you already followed Deploy from a private GitHub repository and added its build-and-publish-only workflow, replace the contents of .github/workflows/docker-image.yml with the workflow below. If you did not add that workflow, create a workflow file such as .github/workflows/deploy-vicugna.yml and put this workflow in it. In either case, disable or remove any other workflow that also publishes the same image tags, so the image is built and published once before the service restart.

name: Build and deploy to Vicugna

on:
push:
branches:
- main
pull_request:

permissions:
contents: read
packages: write

concurrency:
group: deploy-vicugna
cancel-in-progress: false

jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4

- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3

- name: Log in to GHCR
if: github.event_name != 'pull_request'
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}

- name: Extract Docker metadata
id: meta
uses: docker/metadata-action@v5
with:
images: ghcr.io/${{ github.repository }}
tags: |
type=sha
type=raw,value=latest,enable={{is_default_branch}}

- name: Build and push image
uses: docker/build-push-action@v6
with:
context: .
file: ./Dockerfile
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}

- name: Install vicu
if: github.event_name != 'pull_request'
run: |
curl -fsSL https://vicugna.cloud/downloads/cli/v26.09.2/vicu-26.09.2-linux-amd64.zip \
-o /tmp/vicu.zip
unzip -q /tmp/vicu.zip -d /tmp/vicu
sudo install -m 0755 /tmp/vicu/vicu /usr/local/bin/vicu
vicu --version

- name: Restart Vicugna service
if: github.event_name != 'pull_request'
env:
VICUGNA_API_KEY: ${{ secrets.VICUGNA_API_KEY }}
VICUGNA_PROJECT_ID: ${{ vars.VICUGNA_PROJECT_ID }}
VICUGNA_SERVICE_ID: ${{ vars.VICUGNA_SERVICE_ID }}
run: |
set -euo pipefail
: "${VICUGNA_PROJECT_ID:?Set the VICUGNA_PROJECT_ID repository variable}"
: "${VICUGNA_SERVICE_ID:?Set the VICUGNA_SERVICE_ID repository variable}"
: "${VICUGNA_API_KEY:?Set the VICUGNA_API_KEY repository secret}"
vicu restart "$VICUGNA_PROJECT_ID" "$VICUGNA_SERVICE_ID"

The CLI download is pinned to version 26.09.2 so builds use a known release. When you choose a newer vicu release, update both version strings in the download URL and ZIP filename.

What happens on each event​

  • A pull request builds the Docker image to check the Dockerfile, but does not publish the image or restart the service.
  • A push to main builds and publishes the image to ghcr.io/OWNER/REPOSITORY, with both a commit SHA tag and latest.
  • After the image push succeeds, the workflow installs vicu and runs vicu restart with the configured project and service IDs.
  • vicu restart requests the restart and returns without waiting for the rollout to finish. A successful request means Vicugna accepted it, not that the service is already healthy.

The sequence matters: the image is pushed before the restart request, so Vicugna can pull the updated latest image when it starts the service. Keep the GHCR package private and make sure the service has valid private GHCR pull credentials; the workflow's GITHUB_TOKEN publishes the image, while the service's configured credentials let Vicugna pull it.

Troubleshooting​

  • If the workflow stops before restarting the service, check the image build and push steps in the Actions run.
  • If vicu reports an authentication error, check that VICUGNA_API_KEY is set to a valid project API key.
  • If it cannot find or access the service, check that the project ID and service ID are correct and belong together.
  • If the restart request succeeds but the service does not become healthy, check the service status and logs in Vicugna, along with its GHCR credentials, and image reference.