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
mainbuilds and publishes the image toghcr.io/OWNER/REPOSITORY, with both a commit SHA tag andlatest. - After the image push succeeds, the workflow installs
vicuand runsvicu restartwith the configured project and service IDs. vicu restartrequests 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
vicureports an authentication error, check thatVICUGNA_API_KEYis 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.