cnpg-postgres-containers/.github/actions/generate-catalogs

Image Catalogs Generator Action

This composite GitHub Action generates CloudNativePG ImageCatalogs from a container registry. It wraps the catalogs_generator.py script and makes it easy to run inside CI pipelines.

---

How it works

1. The script retrieves all image tags from a container registry.

2. A regular expression is applied to select the tags to include in the ImageCatalog.

3. Matching tags are sorted using semantic versioning.

4. For each PostgreSQL major version, the latest matching tag is chosen.

5. The action generates:

   • One ClusterImageCatalog YAML file per requested distribution and image type
   • A kustomization.yaml to install/update all cluster catalogs at once

---

Inputs

Name	Required	Description	Example
registry	✅ yes	The container registry to query.	ghcr.io/cloudnative-pg/postgresql
image-types	✅ yes	Comma-separated list of image types.	minimal,standard
distributions	✅ yes	Comma-separated list of supported OS distributions.	bookworm,trixie
regex	✅ yes	Regular expression used to match image tags.	See Regex
output-dir	✅ yes	Directory where generated catalogs will be written.	./
family	❌ no	Family name for generated catalogs (filename prefix). Defaults to postgresql.	my-custom-family

---

Regex

The regex input defines which tags are added to the ClusterImageCatalog.

• The first capturing group must be the PostgreSQL major version:

  • (\d+) → e.g. 18

• Subsequent capturing groups are optional and may include:

  • an additional version: (\d+(?:\.\d+)+) → e.g. 1.2.3
  • a 12 digit timestamp: (\d{12}) → e.g. 202509161052

Examples:

# Matches '18-202509161052', '18.1-202509161052', etc.
'(\d+)(?:\.\d+|beta\d+|rc\d+|alpha\d+)-(\d{12})'

# Matches '18-3.0.6-202509161052', '18.1-3.0.6-202509161052', etc.
'(\d+)(?:\.\d+|beta\d+|rc\d+|alpha\d+)-(\d+(?:\.\d+){1,3})-(\d{12})'

Note: Each image-types and distributions will be combined together to form a suffix, -<img_type>-<distribution>, which will internally be appended to the regex provided. Tags that do not contain explicit image type and distribution as a suffix are currently not supported.

---

Family

The optional family input customizes:

1. File prefix: <family>-minimal-trixie.yaml
2. metadata.name in the ImageCatalog: <family>-minimal-trixie
3. images.cnpg.io/family label on the ImageCatalog object

If not specified it defaults to postgresql.

---

Usage

Example workflow:

jobs:
  generate-catalogs:
    runs-on: ubuntu-latest
    steps:
      - name: Generate image catalogs
        uses: cloudnative-pg/postgres-containers/.github/actions/generate-catalogs@main
        with:
          registry: ghcr.io/cloudnative-pg/postgresql
          image-types: minimal,standard
          distributions: bookworm,trixie
          regex: '(\d+)(?:\.\d+|beta\d+|rc\d+|alpha\d+)-(\d{12})'
          output-dir: .

This generates:

./catalog-minimal-bookworm.yaml
./catalog-standard-bookworm.yaml
./catalog-minimal-trixie.yaml
./catalog-standard-trixie.yaml

The generated kustomization.yaml will look like:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- catalog-minimal-bookworm.yaml
- catalog-standard-bookworm.yaml
- catalog-minimal-trixie.yaml
- catalog-standard-trixie.yaml