Guide to Configuring Gitea Actions for Automatic Docker Image Build and Push to GHCR from a Self-Hosted VPS
Detailed guide on setting up Gitea Actions on a self-hosted VPS to automatically build, package, and push Docker images to GitHub Container Registry (GHCR). Covers workflow...
Introduction
In modern software development, automating build, packaging, and deployment processes is essential for ensuring efficiency and reliability. Gitea Actions, similar to GitHub Actions, enables you to create automated workflows on your self-hosted Gitea server, such as a dedicated VPS. This guide will walk you through configuring Gitea Actions to automatically build a Docker image from source code, package it, and push it to GitHub Container Registry (GHCR).
Requirements and Preparation
- A dedicated VPS (refer to NVMe Cloud VPS for Docker, Nginx & Databases).
- SSH access or root privileges to the VPS.
- Git and Gitea installed and configured on the VPS.
- GitHub account with access to GitHub Container Registry (GHCR).
- GitHub personal access token (PAT) with
repoandpackagespermissions. - Application source code containing a Dockerfile.
Setting Up Gitea Actions on the VPS
To use Gitea Actions, ensure Gitea is configured to support actions. On the dedicated VPS, follow these steps:
- Ensure the latest version of Gitea is installed. Gitea Actions are supported from version 1.15 onwards.
- Create a
.gitea/workflowsdirectory in your repository. - Create a
docker-build-push.ymlfile in this directory with the following content:
name: Build and Push Docker Image
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build-and-push:
runs-on: self-hosted
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-qemu-action@v3
with:
platforms: linux/amd64
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Login to GitHub Container Registry
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ secrets.GHCR_USERNAME }}
password: ${{ secrets.GHCR_TOKEN }}
- name: Build and push Docker image
uses: docker/build-push-action@v5
with:
context: .
push: true
tags: ghcr.io/${{ github.repository }}:latest
build-args: |
VERSION=${{ github.sha }}
In this file:
on: pushandon: pull_requestdefine when the workflow runs.runs-on: self-hostedspecifies that the job runs on the self-hosted server (dedicated VPS).Login to GitHub Container Registryuses the environment variablesGHCR_USERNAMEandGHCR_TOKEN.build-push-actionbuilds and pushes the Docker image to GHCR.
Setting Up Environment Variables and Authentication
To allow the workflow to log in to GHCR, you must set up environment variables (secrets) in Gitea:
- Access your repository on Gitea.
- Go to
Settings>Repository settings>Actions. - Select
Secretsand add two variables:
GHCR_USERNAME: Your GitHub username.GHCR_TOKEN: GitHub personal access token withrepoandpackagespermissions.
Ensure the token has access to GHCR. You can create a new token at GitHub Settings > Developer settings > Personal access tokens.
Testing and Verification
After configuration, push a new commit to the main branch to trigger the workflow. You can monitor the process in the Actions tab of your repository on Gitea.
To verify that the Docker image has been successfully pushed to GHCR, run the following command on the dedicated VPS:
docker pull ghcr.io/your-username/your-repo:latest
Replace your-username and your-repo with your actual username and repository name. If the command succeeds, the image has been pushed to GHCR.
Troubleshooting
- Workflow does not run: Check if Gitea supports Actions and if the Gitea version is recent enough. Review the job logs for errors.
- Cannot log in to GHCR: Ensure the token has
packagesandrepopermissions. Verify theGHCR_USERNAMEandGHCR_TOKENenvironment variables in Gitea. - Image not appearing on GHCR: Check the job logs for Docker build errors. Ensure the Dockerfile exists and is correctly formatted.
References
Notes: This guide is based on general technical knowledge of Gitea Actions and GitHub Container Registry. No specific web documentation was cited in the retrieval results, so the steps are synthesized from common technical practices and real-world configurations.
Related infrastructure & engineering guides: MeshCentral: Enterprise Remote IT Management and Support Center via Browser
Recommended NVMe Cloud VPS Plans to Deploy This Setup
Enterprise RAID 10 NVMe SSDs, CMC & FPT District 9 uplinks with Anycast Anti-DDoS and 99.99% SLA.
VPS-3E
10% VAT included
- CPU: 2 vCPU
- RAM: 4 GB
- SSD: 50 GB NVMe
