# Contributing to fedora-bootc base images

## Prerequisites

Everything revolves around our Containerfile, but there's
a high level wrapper in `Justfile` which you should use.
So installing `podman` (or `buildah`) and `just` are strongly recommended.

## Building and testing

Run `just --list` to see available targets and `just show-config` to
see current settings. The Justfile is also what CI invokes, so anything
you run locally is the same as what runs in the pipeline.

Configuration is via environment variables — see the comments at the
top of the `Justfile` for the full list. For example:

```bash
just build                                    # defaults
TIER=minimal just build                       # different tier
FEDORA_VERSION=43 just test                   # different Fedora version
BUILDER=podman just build                     # use podman instead of buildah
just ci                                       # full CI run (validate + test all tiers)
```

## Building a split image

The Containerfile supports building a split (content-based layered)
image using [chunkah](https://github.com/coreos/chunkah) via the
`chunked` build target:

```bash
just build --chunkah
```

Extra arguments can be passed to chunkah via the `CHUNKAH_ARGS` build
arg (e.g. `BUILDER_EXTRA='--build-arg CHUNKAH_ARGS="--max-layers 128"' just build --chunkah`).

## Running Renovate on demand

Dependency update MRs are created by Renovate running in Konflux
([MintMaker](https://konflux-ci.dev/docs/mintmaker/user/)). It runs on a
cluster-wide schedule (roughly every 4 hours, with a 4 hour lookup cache;
the Tekton manager only runs on Saturdays), and cannot be triggered early
from this repository — ticking Dependency Dashboard checkboxes only takes
effect on the next scheduled run.

`just renovate` runs Renovate yourself, using the same container image and
[global configuration](https://github.com/konflux-ci/mintmaker/blob/main/config/renovate/renovate.json)
as MintMaker, with the schedule restrictions removed.

### Creating a GitLab token

Create a fine-grained personal access token: avatar → **Edit profile** →
**Access** → **Personal access tokens** → **Generate token** →
**Fine-grained token**.

- Set a short expiration date.
- Under **Group and project access**, choose **Selected memberships** and
  select the `fedora/bootc` group (or just the `fedora/bootc/base-images`
  project, plus your fork if you want to test against it).
- Add the following permissions:

| Tab               | Category         | Resource      | Permissions                 |
| ----------------- | ---------------- | ------------- | --------------------------- |
| Group and project | Projects         | Project       | Read                        |
| Group and project | Repository       | Code          | Download, Push              |
| Group and project | Repository       | Repository    | Read                        |
| Group and project | Repository       | Branch        | Read, Create, Delete        |
| Group and project | Repository       | Commit        | Read, Create                |
| Group and project | Repository       | Merge Request | Read, Create, Update, Merge |
| Group and project | Project Planning | Work Item     | Read, Create, Update        |
| Group and project | Project Planning | Label         | Read                        |
| Group and project | CI/CD            | Pipeline      | Read                        |
| Group and project | CI/CD            | Commit Status | Create                      |
| User              | System Access    | User          | Read                        |
| Global            | System Access    | Metadata      | Read                        |

Export the token as `RENOVATE_TOKEN`. Optionally, export a GitHub token
(no extra permissions needed, created at <https://github.com/settings/tokens>)
as `RENOVATE_GITHUB_COM_TOKEN` to avoid GitHub API rate limits when fetching
shared presets.

### Running

```bash
just renovate --dry-run                       # preview only, nothing is pushed
just renovate                                 # push branches and open/update MRs
LOG_LEVEL=debug just renovate --dry-run       # include full update details
just renovate --dry-run jeckersb/base-images  # run against a fork
```

Commits and MRs will be authored by the token's user rather than the
`konflux` bot. They use the same branches as the bot (`konflux/mintmaker/*`
and `renovate/fedora-*/*`), so no duplicate MRs are created. On-demand runs
update the bot's existing MRs, but the bot only tracks MRs it created
itself, so any new MR opened by an on-demand run stays yours until it is
merged or closed. On-demand runs never create or update the Dependency
Dashboard.