Deploy from a private GitHub repository
Use a private GitHub repository and GitHub Actions to build and publish a container image, then configure Vicugna to pull that private image and start your service.
This guide uses a minimal FastAPI application as an example. The deployment flow applies to any HTTP API: the application listens on an HTTP port, the Dockerfile starts it on 0.0.0.0, and CI publishes the image to a registry.
How the deployment works
The deployment has two separate steps:
- GitHub Actions builds the Docker image and publishes it to GitHub Container Registry (GHCR).
- Vicugna pulls that image from GHCR and starts a service from it.
Vicugna does not build your source code or access your private repository. The image must already exist in the private GHCR package before Vicugna can deploy it.
Check the application
Put your application in main.py:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def hello_world() -> dict[str, str]:
return {"message": "Hello, world!"}
It serves a response at / and listens on port 8000 when started with Uvicorn. The important requirements are that the process binds to 0.0.0.0 and that the port matches the port configured in Vicugna.
Build the container
Use a Dockerfile like this:
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY main.py .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
Vicugna uses the HTTP port you enter in the service form to route traffic to the application.
You can test the image locally before pushing it:
docker build -t vicugna-example-app .
docker run --rm -p 8000:8000 vicugna-example-app
Open http://localhost:8000/ and check that the response is:
{"message":"Hello, world!"}
Configure GitHub Actions
Create .github/workflows/docker-image.yml in your GitHub repository:
name: Build and publish Docker image
on:
push:
branches:
- main
pull_request:
workflow_dispatch:
permissions:
contents: read
packages: write
jobs:
docker:
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
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 }}
What the workflow does
- A pull request builds the image but does not publish it. This checks that the Dockerfile works without putting an unmerged image in GHCR.
- A push to
mainlogs in to GHCR using the automatically providedGITHUB_TOKEN, builds the image, and publishes it. permissions.packages: writegives the workflow permission to publish the package.ghcr.io/${{ github.repository }}names the image from the repository owner and repository name. For a repository atgithub.com/OWNER/REPOSITORY, the image is published asghcr.io/OWNER/REPOSITORY.- The workflow publishes a
latesttag for the default branch and a commit SHA tag for each published build. The SHA tag is useful when you need to deploy one exact build instead of whichever image is currently calledlatest.
Push the workflow and application files to main, then open the repository's Actions tab. Wait for Build and publish Docker image to complete successfully before creating the Vicugna service.
Make the private package pullable
The GHCR package is private, so Vicugna needs permission to pull it. Create or use a classic GitHub personal access token with the read:packages scope. You will provide the GitHub username and token to Vicugna when creating the service.
Do not put the token in the Dockerfile, workflow file, image tag, or application source code. The workflow uses the automatically provided GITHUB_TOKEN to publish the package; Vicugna uses the separate read-only credential to pull it.
Create the Vicugna service
After the workflow succeeds, create a service in the Vicugna project:
- Choose New service.
- Enter a hostname, such as
api. - Set Docker image to
ghcr.io/OWNER/REPOSITORY:latest, replacingOWNER/REPOSITORYwith your GitHub repository path. - Set HTTP port to
8000. - Expand Optional private GHCR credentials and enter the GitHub username and the token with
read:packages. - Click Create service.
Vicugna pulls the image, starts the container, and reports the deployment status. Once it is running, choose Generate subdomain on the service detail page to create a public HTTPS address.
Whenever you restart a service, Vicugna pulls the configured Docker image again before starting the container. This applies to restarts initiated from the Vicugna UI and from the CLI. If the service uses a mutable tag such as latest, a restart can therefore pick up a newer image published under that tag.
Troubleshooting
If the workflow fails:
- Check the failed step in the repository's Actions tab.
- Confirm that
permissions.packagesis set towrite. - Confirm that the Dockerfile, application module, and start command agree. The sample starts
main:appwith Uvicorn.
If the Vicugna service does not become healthy:
- Confirm that the image name and tag exist in GHCR.
- Confirm that the username and token are correct and that the token has
read:packages. - Confirm that the Vicugna HTTP port is
8000. - Confirm that the application binds to
0.0.0.0, not only tolocalhost. - Check the service status and logs for application startup errors.