containers/apps/ci-os/README.md

## CI-OS

This container is a little special since it provides a Nix flake designed to generate a docker image to use with 
[Forgejo runners](https://code.forgejo.org/forgejo/runner). It packages essential tools and helper programs to 
streamline the `code.252.no` CI/CD workflows.

We try to reproduce much-used GitHub actions into one package to avoid calling an excessive amount of images in 
Forgejo workflows.

### Supported use cases

* Flux CI/CD testing
* Forgejo comments: post comments to issues
* 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/tommy/ci-os:latest` 
and includes:

- **Nix Environment**: Pre-configured with Nix and essential configurations.
- **Helper Programs**: Bundles `flux-local`, `flux-diff`, `forgejo-comment` 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 named `ci-os` with necessary tools.


### 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](https://code.252.no/tommy/git-sv)                                                     |
| `flux-local`      | Tool for performing local Flux operations and diffs.            | [allenporter/flux-local](https://github.com/allenporter/flux-local)                                  |
| `flux-diff`       | Utility to diff Flux resources locally.                         | [buroa/k8s-gitops](https://github.com/buroa/k8s-gitops/blob/master/.github/workflows/flux-diff.yaml) |
| `forgejo-comment` | Script to post comments on Forgejo merge requests.              | -                                                                                                    |
| `forgejo-release` | Script to create releases in Forgejo.                           | -                                                                                                    |

Other standard packages are provided from nixpkgs. For an up-to-date list have a look at `ci-os` in
[flake.nix](./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` which is 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 use in Kubernetes, but the image may be used with the act runner locally as well.

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

```yaml
[...]
  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
[...]
```