Deploy Forgejo runner to Kubernetes cluster

In my post about migrating from GitHub to Codeberg I was not able to find a suitable alternative for GitHub actions. With GitHub actions I built and published Docker images. Since the migration I was able find solution.

The solution is a Forgejo runner deployed to a private Kubernetes cluster. It is connected to Codeberg and runs my actions the same way as it did on GitHub. Let me walk you through the setup.

Codeberg setup

For the deployment of the Forgejo runner, I have created a Helm Chart: https://kubernetes.build/forgejoRunner/README.html. If you are familiar with Kubernetes and Helm, the deployment is straightforward.

The Helm Chart requires an instance token to register the runner. This token can be generated and copied from Codeberg. Open https://codeberg.org and click on your profile. Then navigate to Settings > Actions > Runners and click on Create new runner. Copy the registration token.

Kubernetes deployment

Once the runner is deployed, check if it shows up on Codeberg. Open Settings > Actions > Runners and you should see your registered runner.

The Chart also creates a new cluster role called buildx. This role shall be used to access the cluster and build the Docker image in Kubernetes enviroment. Export the kubeconfig of this role like this: https://kubernetes.build/forgejoRunner/README.html#forgejo-buildx-action

Forgejo action

The last step is the migration of the GitHub action and enabling the Codeberg repository to run actions.

Let’s get started by enabling actions on the repo. Open the Settings page of your repo and click on Units > Overview. Enable the Actions option and save the settings. A new tab Actions and a settings page are shown now.

We assume that you have a GitHub action .github/workflows/build.yml in your repo. Rename the .github folder to .forgejo.

A few modifications of the build.yml workflow are required to get the same results in the Forgejo runner environment.

First we need to define the build environment. Update the build.yml with this containerkey:

...
jobs:
  build:
	...
    container: catthehacker/ubuntu:act-latest

The ubuntu:act-latest Docker image replicates the GitHub build environment.

Next we need to grant the Forgejo runner access to the Kubernetes environment.

	  - name: Checkout code
		uses: actions/checkout@v4
	
	  - name: Create Kubeconfig for Buildx
		run: |
		  mkdir -p $HOME/.kube
		  echo "${{ secrets.KUBECONFIG_BUILDX }}" > $HOME/.kube/config

As you can see the the kubeconfig is loaded from a environment secret. Setup this secret in your organisation or personal account. Open Settings > Actions > Secrets and click Add secret. Enter KUBECONFIG_BUILDX as name enter the content of the kubeconfig from the Codeberg setup step.

We are almost done. In order to build and publish a Docker image, these steps have to be added as well:

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
          driver: kubernetes
          driver-opts: |
                        namespace=codeberg

      - name: Login to Docker Registry
        uses: docker/login-action@v3
        with:
          username: janikvonrotz
          password: ${{ secrets.DOCKER_PAT }}

The namespace=codeberg definition must be match the namespace name of Forgejo runner deployed. Add the DOCKER_PAT as a secret to your account.

Checkout the full reference of the build.yml: https://codeberg.org/janikvonrotz/janikvonrotz.ch/src/branch/main/.forgejo/workflows/build.yml

Run the action

Everything is ready to run. Once you commit and push the new .forgejo/workflows/build.yml file, the following should happen:

1. Codeberg creates a new action run
2. The Forgejo runner receives the task and runs the build image
3. In the build container the repository is cloned
4. The kubeconfig is created and the Docker Buildx enviroment is prepared
5. The build container builds the Docker image in the Kubernetes environment
6. If successful, the image is pushed to the Docker registry

Next steps

The image is now ready to deploy. How to trigger a Kubernetes deployment from a Forgejo action will be covered in another post.

Credits

I give my thanks to Tobias Brunner. He gave me the initial configs for the setup:

Forgejo Runner Helm Chart: https://git.tbrnt.ch/tobru/gitops-zurrli/src/branch/main/apps/zurrli/forgejo-runner

Build and Deploy action: https://git.tbrnt.ch/tobru/tobrublog/src/branch/main/.forgejo/workflows/build-deploy.yaml