Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Cachi2 Lock File generator doc #1305

Open
wants to merge 1 commit into
base: gh-pages
Choose a base branch
from
Open

Cachi2 Lock File generator doc #1305

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions guide/build-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -489,6 +489,29 @@ Note that the following configuration options are currently **not** supported by

To test `BOM` strategy locally, an existing config using `RESOLVE_ONLY` should simply be updated to use the `BOM` strategy. Here is a sample command line that generates RHBQ 3.2.9 Maven repository ZIP:

###### Cachi2 Lock File Generation

The `BOM` strategy offers an option to capture the resolved artifacts with the `redhat` version qualifier and generate a Cachi2 Lock File that can be used later to prefetch the generated MRRC ZIP content into a Konflux pipeline for container image building or an MRRC release process.

> [!NOTE]
> It's also possible to configure the `cachi2LockFile` addon as an alternative. The difference between these options is that the addon will be deriving artifact coordinates (groupId, artifactId, classifier, extension and version) from the file names found in the ZIP (which in certain edge cases might not be reliable), while the BOM strategy will capture all the artifact coordinates during the resolution process.

To enable Cachi2 Lock File generation the `cachi2LockFile` parameter has to be set to the desired target file path. For example

```yaml
flow:
licensesGeneration:
strategy: GENERATE
repositoryGeneration:
strategy: BOM
parameters:
bomGavs: >-
com.redhat.quarkus.platform:quarkus-bom:{{quarkusPlatformVersion}}
cachi2LockFile: extras/quarkus-platform-{{quarkusPlatformVersion}}-cachi2-lockfile.yaml
```

With the configuration above, the Cachi2 Lock File will be saved in the `{RELEASE_DIR}/extras/quarkus-platform-{QUARKUS_PLATFORM_VERSION}-cachi2-lockfile.yaml`.

```
java -jar bacon.jar pig run --clean --skipBuilds --skipBranchCheck --skipPncUpdate --skipLicenses --skipSources --releaseStorageUrl https://download.eng.bos.redhat.com/rcm-guest/staging/quarkus config-dir/ --targetPath deliverables
```
Expand Down
38 changes: 38 additions & 0 deletions guide/pig.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,11 @@ The `configure` phase pushes all the settings in the YAML file to PNC, and the `
bacon pig <phase> ...
```

## Other PiG commands

The following `pig` subcommands are available but not tied to any specific phase:

- cachi2lockfile

# Configuration

Expand Down Expand Up @@ -294,8 +299,41 @@ addons:
#### Using Defaults
To use default value for an optional parameter leave that parameter undefined in the addons section of your build-config.yaml file.

### Cachi2 Lock File Generator

This add-on generates a Cachi2 Lock File for the produced Maven repository ZIP (regardless which strategy was used to generate it). Cachi2 Lock Files can be used to prefetch Maven content to Konflux pipelines for container image and MRRC release processes.

The add-on can be configured in the following way:

```
addons:
cachi2LockFile:
filename: mrrc-cachi2-lockfile.yaml
```

The `filename` parameter is optional and defaults to `cachi2lockfile.yaml` if not configured. The file will be stored under the `extras` directory.

{% endraw %}

## cachi2lockfile command

This `pig cachi2lockfile` CLI command allows generating a Cachi2 lockfile for a given Maven repository. The command will not perform any Maven artifact resolution, it will simply describe the content of a Maven repository in the Cachi2 lock file format.

The command accepts ZIP files and/or directories that include Maven repository content under `maven-repository` subdirectory (to be compliant with the way Bacon generates Maven repository ZIPs). For example:

```
bacon pig cachi2lockfile rh-quarkus-platform-3.15.2.CR1-maven-repository.zip
```

Multiple repository paths (including a mix of directories and ZIPs) can be provided using comma as a separator.

By default, the generated lock file will be named `artifacts.lock.yaml`, since this is what Cachi2 to will expect by default. A different file name can be specified by adding the `--output` argument with the desired value.

Other command options include:

* `--maven-repository-url` - the desired value of the Maven repository URL to record for each artifact. The default value will match the one configured in the local Bacon config;
* `--preferred-checksum-alg` - the lock file format expects a single checksum. By default, the tool will use the highest version of the `SHA` checksum available in the Maven repository. This option allows to specify an alternative checksum algorithm (assuming it's available in the repository), if the default is not good enough.

## PiG Export Feature

### Build Configuration Export
Expand Down