Migration Guidelines for Binary Artefacts Repository (BAR)

This page describes example use cases that have been identified on the SKAO project and provides guidelines for an easier migration.

Note

BAR v1 and v2 APIs are no longer supported. Please use the v3 API.

General Guidance

  1. Do: Use the Gitlab pipeline job for raw-artefacts. See Gitlab Pipeline.

  2. Do: Provide as much metadata as possible in the form of annotations. See Annotations.

  3. Do: Use the BAR API to find the correct artefact to download. See List repositories.

  4. Do: Flatten the target path/repo into the artefact name and use the version field to keep track of changes.

  5. Do: Push the files that make up the artefact version as artefact assets. See Upload an artefact.

  6. Do not: Use SHA-256 as part of the name, as this is created automatically and added as a metadata property for the artefact.

  7. Do not: Parse the HTML output of the BAR UI to find and download artefacts.

Request an API Key

Publishing an artefact should be done (where applicable) using the Gitlab pipeline. In other scenarios, the UI should be used. Nonetheless, to use the BAR v3 API properly, you need a valid API Key (JWT Token). To request one, please create an STS ticket and provide the repositories and artefact names you want to have access to.

Downloading Artefacts

  1. Use the BAR API - instead of the Nexus search API - to find the correct artefact to download: Get Artefacts

  2. Secure your API tokens

  3. Create permalinks or presigned URLs to avoid using a token in application deployments when the artefact can be publicly accessed: Presign and Permalinks

  4. As artefacts can be composed of multiple assets, be sure to craft your URLs to download precisely what you intend to

Please refer to Examples for more information.

Uploading Artefacts

As mentioned before, the Gitlab Pipeline should be used to publish artefacts with all the intended metadata. If that is not possible, the UI or API should be used. Please follow Upload an artefact to learn about best practices.

SDP TelModel (STS-608)

The target repo can be flattened into the name. For example, sts-608/gitlab/<repo>/largefiles becomes telmodel-<repo>-largefiles as the artefact name and the version can be anything, preferably semver.

p4-switch-internal

The SDE folder should instead be the artefact name and each file can have different versions as required. For example:

  1. Alternative 1: artefact name: sde; version: bf-reference-bsp-9.13.0.

  2. Alternative 2: artefact name: sde-bf-reference-bsp; version 9.13.0.

raw-telmodel

The target repo can be flattened into the name. For example, gitlab.com/ska-telescope/gitlab/<project>/<repo>/ becomes telmodel-<project>-<repo> as the artefact name and the version can be anything to keep track of the different tmdata contents’ versions.

raw-internal

Valid artefacts in this repository were migrated to https://binary.artefact.skao.int/artefacts/raw-artefacts. Publishing new artefacts should be done exclusively using the Gitlab pipeline.