CI-OS

This image is an Action build container for Forgejo runners. It embeds build packages required to manage and push packages to a Forgejo repo and registries.

We we CI-OS to streamline the code.252.no CI/CD workflows.

The advantage of using CI-OS is that it is a single container image that can be used in any Forgejo workflow and it reproduce much-used GitHub actions into one package to avoid calling an excessive amount of images in the workflows.

Supported Use Cases

• Flux CI/CD testing
• Forgejo comments (posting comments to issues and PRs)
• Run commands ad-hoc with nix run

Docker Image Info

The latest container resulting from the Nix build is located in the registry at code.252.no/pub/ci-os:latest, which includes:

• Nix Environment: Pre-configured with Nix and essential configurations.
• Helper Programs: Bundles flux-local, flux-diff, forgejo-comment, forgejo-release, and more.
• Essential Build Tools: Includes utilities like git, docker, bash, curl, jq, and more.

Nix Flake Info

• Apps: Accessible via nix run or nix shell commands.
• Packages: Builds the ci-os Docker image with necessary toolchains.

Including Individual Apps in Your Own Flake

If you only need specific tools—for example, just forgejo-release you can pull that package into your own Nix flake without bundling the entire Docker image or all CI-OS tools.

For instance, if your flake.nix references this repository as ci-os:

{
  inputs = {
    # Replace with your actual reference
    nixpkgs.url = "github:NixOS/nixpkgs";
    ci-os.url   = "code.252.no/pub/ci-os";
  };

  outputs = { self, nixpkgs, ci-os, ... }:
    let
      system = "x86_64-linux"; # or aarch64-linux, etc.
    in
    {
      # Example: Provide a package named `my-forgejo-release`
      packages.${system}.my-forgejo-release = ci-os.packages.${system}.forgejo-release;

      # You could also define an 'app' to run 'forgejo-release' directly
      apps.${system}.forgejo-release = {
        derivation = ci-os.packages.${system}.forgejo-release;
        # Optionally add a description or other metadata
      };
    };

• Run it directly:

  nix run .#my-forgejo-release -- --help
  

  or

  nix run .#forgejo-release -- --help
  

• Open a shell with it:

  nix shell .#my-forgejo-release
  forgejo-release --help
  

This allows you to install or run individual commands (e.g., forgejo-release or flux-diff) without downloading and using the entire ci-os Docker image.

Helper Programs Provided

The flake provides the following applications:

Application	Description	External Ref
git-sv	Semantic versioning tool for git based on conventional commits.	tommy/git-sv
flux-local	Tool for performing local Flux operations and diffs.	allenporter/flux-local
flux-diff	Utility to diff Flux resources locally.	buroa/k8s-gitops
forgejo-comment	Script to post comments on Forgejo merge requests.	-
forgejo-release	Script to create and manage releases in Forgejo.	-

Other standard packages are provided from nixpkgs. For an up-to-date list, see ci-os in flake.nix.

Templates

In a runner, you can reference /var/ci-os/templates to find templates for release notes and more.

Usage

Building

We provide an example Taskfile in task ci-os:build, used for manual builds at code.252.no. The task uses nerdctl, but you may replace this with docker or podman. To publish the image, use task ci-os:publish.

In Runner

We provide examples for using the image in Kubernetes, but the image may also be used with the act runner locally.

To use the Docker image in your Forgejo runner, add it to your Helm values (this uses the bjw-s app-template):

[...]
  values:
    controllers:
      forgejo-runner-elkworks:
        replicas: 2
        initContainers:
          runner-register:
            image:
              repository: code.forgejo.org/forgejo/runner
              tag: 4.0.1
            command:
            - "forgejo-runner"
            - "register"
            - "--no-interactive"
            - "--token"
            - $(RUNNER_TOKEN)
            - "--name"
            - $(RUNNER_NAME)
            - "--instance"
            - $(FORGEJO_INSTANCE_URL)
            - "--labels"
            - "ci-os:docker://code.252.no/tommy/ci-os:latest,[...]"
            env:
            - name: RUNNER_TOKEN
              valueFrom:
                secretKeyRef:
                  name: forgejo-runner-elkworks-secret
                  key: RUNNER_TOKEN
            - name: RUNNER_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: FORGEJO_INSTANCE_URL
              value: https://code.252.no
[...]