Back to articles
DevOps & Systems

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...

DPTCloud Engineering4 min read
Guide to Configuring Gitea Actions for Automatic Docker Image Build and Push to GHCR from a Self-Hosted VPS

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 repo and packages permissions.
  • 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:

  1. Ensure the latest version of Gitea is installed. Gitea Actions are supported from version 1.15 onwards.
  2. Create a .gitea/workflows directory in your repository.
  3. Create a docker-build-push.yml file 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: push and on: pull_request define when the workflow runs.
  • runs-on: self-hosted specifies that the job runs on the self-hosted server (dedicated VPS).
  • Login to GitHub Container Registry uses the environment variables GHCR_USERNAME and GHCR_TOKEN.
  • build-push-action builds 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:

  1. Access your repository on Gitea.
  2. Go to Settings > Repository settings > Actions.
  3. Select Secrets and add two variables:
  • GHCR_USERNAME: Your GitHub username.
  • GHCR_TOKEN: GitHub personal access token with repo and packages permissions.

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 packages and repo permissions. Verify the GHCR_USERNAME and GHCR_TOKEN environment 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

DPTCloud Tier III Infrastructure

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.

View 22 VPS Plans
ECO · vn-02

VPS-2E

94.600 ₫ / mo

10% VAT included

  • CPU: 2 vCPU
  • RAM: 2 GB
  • SSD: 30 GB NVMe
ECO · vn-02Recommended

VPS-3E

170.500 ₫ / mo

10% VAT included

  • CPU: 2 vCPU
  • RAM: 4 GB
  • SSD: 50 GB NVMe
BASIC · vn-01Recommended

VPS-05

457.600 ₫ / mo

10% VAT included

  • CPU: 4 vCPU
  • RAM: 8 GB
  • SSD: 50 GB NVMe

Related Articles

View all
ZaloZalo SupportDiscord0384 753 478