From 76f6eaa6da41545a17aed8cea5519ff66c6d5b2d Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Fri, 21 Nov 2025 09:17:21 +0100
Subject: [PATCH 01/20] Import development.

---
 .github/workflows/update-index.yml |  81 +++++++++++++++++++
 generator.py                       | 121 +++++++++++++++++++++++++++++
 issue_dispatch.sh                  |  24 ++++++
 3 files changed, 226 insertions(+)
 create mode 100644 .github/workflows/update-index.yml
 create mode 100644 generator.py
 create mode 100644 issue_dispatch.sh

diff --git a/.github/workflows/update-index.yml b/.github/workflows/update-index.yml
new file mode 100644
index 0000000..ed287a8
--- /dev/null
+++ b/.github/workflows/update-index.yml
@@ -0,0 +1,81 @@
+name: |
+  Updates the package index upon an event. Which repo should be updated depends on the
+  `"source_repo"` payload of the request.
+
+on:
+  repository_dispatch:
+    types: [update_package_index]
+  workflow_dispatch:
+    inputs:
+      source_repo:
+        description: 'Name of the repo that contains the dependency.'
+        required: true
+        type: string
+      source_org:
+        description: 'Name of the organization/user that owns the dependency repo.'
+        required: true
+        type: string
+      dependency_ref:
+        description: 'Reference that in the dependency repo that should be checked out and turned into a dependency.'
+        required: true
+        type: string
+
+jobs:
+  update-index:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Print all variables
+        shell: bash
+        run: |
+          echo "source_repo: ${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}"
+          echo "source_org:  ${{ inputs.source_org == '' && github.event.client_payload.source_org || inputs.source_org }}"
+          echo "dep_ref:     ${{ inputs.dependency_ref == '' && github.event.client_payload.dependency_ref || inputs.dependency_ref }}"
+
+      - name: Checkout `master` branch of the index repo.
+        uses: actions/checkout@v4
+        with:
+          path: index_repo
+          ref: master    # We always work on master!
+
+      - name: Checkout the dependency that should be updated in the index.
+        uses: actions/checkout@v4
+        with:
+          # Everything we pull is publich, so no token needed.
+          repository: ${{ inputs.source_org == '' && github.event.client_payload.source_org || inputs.source_org }}/${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}
+          path: ${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}
+          submodules: 'recursive'
+          ref: ${{ inputs.dependency_ref == '' && github.event.client_payload.dependency_ref || inputs.dependency_ref }}
+
+      - name: Build the distribution.
+        shell: bash
+        run: |
+          DEPENDENCY_REPO="${PWD}/${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}"
+          DIST_FOLDER="${PWD}/index_repo/${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}"
+
+          cd "${DEPENDENCY_REPO}"
+          python -m pip install build --user
+          python -m build --wheel --outdir "${DIST_FOLDER}"
+
+      - name: Create a PR in the index repo
+        shell: bash
+        env:
+          CI_COMMIT_MESSAGE: updated dependency "${{ inputs.source_org == '' && github.event.client_payload.source_org || inputs.source_org }}/${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}"
+          CI_COMMIT_AUTHOR: github-actions[bot]
+          CI_COMMIT_EMAIL: username@users.noreply.github.com
+        run: |
+          cd ./index_repo
+          if ! git status --porcelain --untracked-files=no ; then
+            # There are no changed.
+            echo "There were no changes!"
+            exit 0
+          fi
+
+          # Update all the packages.
+          python generator.py
+
+          # We directly push to master.
+          git config --global user.name "${{ env.CI_COMMIT_AUTHOR }}"
+          git config --global user.email "${{ env.CI_COMMIT_EMAIL }}"
+          git add .
+          git commit --no-verify -m "${CI_COMMIT_MESSAGE}"
+          git push origin master
diff --git a/generator.py b/generator.py
new file mode 100644
index 0000000..8b28f7d
--- /dev/null
+++ b/generator.py
@@ -0,0 +1,121 @@
+"""Regenerates the index based on the specified folders.
+"""
+from typing import Final, Sequence
+
+import hashlib
+import pathlib
+import re
+import sys
+
+HTML_HEADER: Final[str] = """\
+<!DOCTYPE HTML>
+<html>
+    <head>
+        <title>{Title}</title>
+        <meta charset="UTF-8" />
+    </head>
+
+    <body>
+    <h1>{Title}</h1>
+"""
+"""The header for a html page.
+
+It contains the opening `<body>` tag and has the `Titel` interpolation.
+"""
+
+HTML_FOOTER: Final[str] = """\
+    </body>
+</html>
+"""
+"""Contains the footer of an html page.
+
+This includes the closing `</body>` tag.
+"""
+
+def normalize_name(name: str) -> bool:
+    """Normalize the project name according to the rules in PEP503."""
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def write_project_index(
+        base_folder: pathlib.Path,
+        project_name: str,
+) -> int:
+    # Project folder must exists because we assume that the files are located inside.
+    project_folder = base_folder / project_name
+    if not project_folder.is_dir():
+        raise NotADirectoryError(
+                f"Expected that the project folder `{project_folder}` for project `{project_name}` exists."
+    )
+
+    found_packages = 0
+    normalized_project_name = normalize_name(project_name)
+    with open(project_folder / "index.html", "wt") as index:
+        index.write(HTML_HEADER.format(Title=f"Custom Package for '{project_name}'"))
+
+        for file in project_folder.iterdir():
+            filename = file.name
+            if filename.startswith("."):
+                continue
+            elif not any(filename.endswith(ext) for ext in [".zip", ".tar.gz", ".whl"]):
+                continue
+            assert filename.startswith(normalized_project_name + "-")
+
+            # Compute the hash such that we can append it to the link.
+            with open(file, "rb") as F:
+                digest = hashlib.file_digest(F, "sha256")
+
+            # PEP503 says that the text of the anchor element must be the filename, so there
+            #  is not need for fancy processing of the file name. Furthermore, we assume that
+            #  the file names have the correct normalized name and version.
+            index.write(
+                    f'\t\t<a href="{filename}#sha256={digest.hexdigest()}">{filename}</a> </br>\n'.replace("\t", "    ")
+            )
+            found_packages += 1
+        index.write(HTML_FOOTER)
+
+        return found_packages
+
+
+def write_package_index(
+        base_folder: pathlib.Path,
+        packages: Sequence[str],
+) -> None:
+
+    with open(base_folder / "index.html", "wt") as index:
+        index.write(HTML_HEADER.format(Title=f"Custom Package Index for GT4Py"))
+
+        for project_name in packages:
+            project_folder = base_folder / project_name
+            normalized_project_name = normalize_name(project_name)
+            if not project_folder.is_dir():
+                print(
+                        f"There is not folder associated to the project `{project_name}`, skipping it.",
+                        flush=True,
+                        file=sys.stderr,
+                )
+                continue
+
+            # Now generate the index for that file.
+            found_packages = write_project_index(base_folder, project_name)
+
+            if found_packages == 0:
+                # Consider no packages not as an error, only output a warning.
+                # TODO: Consider removing the folder.
+                print(
+                        f"No packages for project `{project_name}` could be located.",
+                        flush=True,
+                        file=sys.stderr,
+                )
+                continue
+
+            index.write(f'\t\t<a href="{project_name}">{normalized_project_name}</a>\n'.replace("\t", "    "))
+
+        index.write(HTML_FOOTER)
+
+
+if __name__ == "__main__":
+    write_package_index(
+            base_folder=pathlib.Path(__file__).parent,
+            packages=["dace", "ghex"],
+    )
diff --git a/issue_dispatch.sh b/issue_dispatch.sh
new file mode 100644
index 0000000..f6c6ce1
--- /dev/null
+++ b/issue_dispatch.sh
@@ -0,0 +1,24 @@
+#!/bin/bash
+
+REPO="test_package_index"
+OWNER="philip-paul-mueller"
+
+SOURCE_REPO="dace"
+SOURCE_ORG="gridtools"
+DEPENDENCY_REF="gt4py-next-integration"
+
+if [ ! -e ".token" ]
+then
+	echo "The file with the token, '.token' does not exist."
+	echo " According to 'https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#create-a-repository-dispatch-event'"
+	echo " a fine grained token with '\"Contents\" repository permissions (write)' is needed."
+	exit 1
+fi
+
+curl -L -v \
+  -X POST \
+  -H "Accept: application/vnd.github+json" \
+  -H "Authorization: Bearer $(cat .token)" \
+  -H "X-GitHub-Api-Version: 2022-11-28" \
+  https://api.github.com/repos/${OWNER}/${REPO}/dispatches \
+  -d '{"event_type":"update_package_index","client_payload":{"source_repo":"'"${SOURCE_REPO}"'","source_org":"'"${SOURCE_ORG}"'","dependency_ref":"'"${DEPENDENCY_REF}"'"}}'

From a9daf5c6fd694283c8992bc1dc96a10868f66180 Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Fri, 21 Nov 2025 09:18:06 +0100
Subject: [PATCH 02/20] Small renaming.

---
 .../workflows/{update-index.yml => update-python-pkg-index.yml}   | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename .github/workflows/{update-index.yml => update-python-pkg-index.yml} (100%)

diff --git a/.github/workflows/update-index.yml b/.github/workflows/update-python-pkg-index.yml
similarity index 100%
rename from .github/workflows/update-index.yml
rename to .github/workflows/update-python-pkg-index.yml

From b9e2b9513daaad783917667d1b9cc08bdcf496d5 Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Fri, 21 Nov 2025 09:22:40 +0100
Subject: [PATCH 03/20] Switched from master to main.

---
 .github/workflows/update-python-pkg-index.yml | 20 +++++++++----------
 1 file changed, 9 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/update-python-pkg-index.yml b/.github/workflows/update-python-pkg-index.yml
index ed287a8..41f2003 100644
--- a/.github/workflows/update-python-pkg-index.yml
+++ b/.github/workflows/update-python-pkg-index.yml
@@ -1,6 +1,4 @@
-name: |
-  Updates the package index upon an event. Which repo should be updated depends on the
-  `"source_repo"` payload of the request.
+name: Updates the Python package index upon an event. 
 
 on:
   repository_dispatch:
@@ -31,32 +29,32 @@ jobs:
           echo "source_org:  ${{ inputs.source_org == '' && github.event.client_payload.source_org || inputs.source_org }}"
           echo "dep_ref:     ${{ inputs.dependency_ref == '' && github.event.client_payload.dependency_ref || inputs.dependency_ref }}"
 
-      - name: Checkout `master` branch of the index repo.
+      - name: Checkout the `main` branch of the Python package index.
         uses: actions/checkout@v4
         with:
           path: index_repo
-          ref: master    # We always work on master!
+          ref: main    # We always work on main!
 
-      - name: Checkout the dependency that should be updated in the index.
+      - name: Checkout the repo of the dependency that should be added to the index.
         uses: actions/checkout@v4
         with:
-          # Everything we pull is publich, so no token needed.
           repository: ${{ inputs.source_org == '' && github.event.client_payload.source_org || inputs.source_org }}/${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}
           path: ${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}
           submodules: 'recursive'
           ref: ${{ inputs.dependency_ref == '' && github.event.client_payload.dependency_ref || inputs.dependency_ref }}
 
-      - name: Build the distribution.
+      - name: Build the distribution file.
         shell: bash
         run: |
           DEPENDENCY_REPO="${PWD}/${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}"
           DIST_FOLDER="${PWD}/index_repo/${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}"
 
+          # TODO: Test if we can install it.
           cd "${DEPENDENCY_REPO}"
           python -m pip install build --user
           python -m build --wheel --outdir "${DIST_FOLDER}"
 
-      - name: Create a PR in the index repo
+      - name: Rescan the package index and update the static `index.html` files.
         shell: bash
         env:
           CI_COMMIT_MESSAGE: updated dependency "${{ inputs.source_org == '' && github.event.client_payload.source_org || inputs.source_org }}/${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}"
@@ -73,9 +71,9 @@ jobs:
           # Update all the packages.
           python generator.py
 
-          # We directly push to master.
+          # We directly push to main!
           git config --global user.name "${{ env.CI_COMMIT_AUTHOR }}"
           git config --global user.email "${{ env.CI_COMMIT_EMAIL }}"
           git add .
           git commit --no-verify -m "${CI_COMMIT_MESSAGE}"
-          git push origin master
+          git push origin main

From c015a2cb4419cf3ad7b7fde3420a5b1fadba14ea Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Fri, 21 Nov 2025 10:55:15 +0100
Subject: [PATCH 04/20] First version.

---
 .gitignore                  |  19 +------
 README.md                   |  46 +++++++++++++++-
 generator.py                |   9 ++-
 issue_dispatch.sh           |  24 --------
 issue_update.sh             | 107 ++++++++++++++++++++++++++++++++++++
 update-python-pkg-index.yml |   1 +
 6 files changed, 159 insertions(+), 47 deletions(-)
 delete mode 100644 issue_dispatch.sh
 create mode 100644 issue_update.sh
 create mode 120000 update-python-pkg-index.yml

diff --git a/.gitignore b/.gitignore
index 493e69b..d20209c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,18 +1 @@
-# This .gitignore is appropriate for repositories deployed to GitHub Pages and using
-# a Gemfile as specified at https://github.com/github/pages-gem#conventional
-
-# Basic Jekyll gitignores (synchronize to Jekyll.gitignore)
-_site/
-.sass-cache/
-.jekyll-cache/
-.jekyll-metadata
-
-# Additional Ruby/bundler ignore for when you run: bundle install
-/vendor
-
-# Specific ignore for GitHub Pages
-# GitHub Pages will always use its own deployed version of pages-gem 
-# This means GitHub Pages will NOT use your Gemfile.lock and therefore it is
-# counterproductive to check this file into the repository.
-# Details at https://github.com/github/pages-gem/issues/768
-Gemfile.lock
+.token*
diff --git a/README.md b/README.md
index 3502756..b3f72e1 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,44 @@
-# pypi-index
-Python packages index
+# Custom GT4Py Python Package Index Server
+This repo hosts the custom packages that are needed to use GT4Py, these currently includes:
+- [GridTools/dace](https://github.com/GridTools/dace), currently only for the `next`.
+- [ghex-org/GHEX](https://github.com/ghex-org/GHEX)
+
+# Usage
+The repo is intended to work fully automatically, orchestrated by GitHub actions.
+
+## Workflow `update-python-pkg-index.yml`
+This is the main workflow, in short it does:
+- Pulls the repo, whose package should be updated.
+- Creates a wheel from the repo that has been pulled.
+- Updated the package index, i.e. regenerates the `index.html` files, for this `generator.py` is used.
+- Creates a commit containing the updated indexes and the generated wheel.
+- Pushes the new commit directly to `main`.
+
+The workflow can be started manually, either through the GitHub web interface or through the `issue_update.sh` script.
+In either case some information have to be provided:
+- The name of the repo on GitHub, generally referred to as "source repo".
+- The owner (user or organization) that owns the repo, generally referred to as "source owner".
+- The branch of the repo from which a Python package should be created, generally referred to as "dependency ref".
+
+## `generator.py`
+Script for updating the static pages.
+It works by scanning subfolders, currently `dace` and `ghex`, and creates an index based on all Python packages it founds in them.
+It is usually run by by the workflow automatically.
+
+## `issue_update.sh`
+A simple script that allows to issue a manual remote update of the index.
+For more information please see its help output.
+
+
+# How to install a dependency
+TBA:
+
+
+## Token
+In order for the _depending_ repo to issue an update request an access token is needed.
+This can either be a normal (classic) access token, that needs to grant read access to the repository.
+The other possibility is to use a fine grained access token, in which case only the '"Contents" repository permissions (write)' permission has to be granted.
+
+
+# TODO:
+- Test if the wheel can be installed.
diff --git a/generator.py b/generator.py
index 8b28f7d..d691e5a 100644
--- a/generator.py
+++ b/generator.py
@@ -55,9 +55,12 @@ def write_project_index(
 
         for file in project_folder.iterdir():
             filename = file.name
-            if filename.startswith("."):
-                continue
-            elif not any(filename.endswith(ext) for ext in [".zip", ".tar.gz", ".whl"]):
+            if filename.startswith(".") or not any(filename.endswith(ext) for ext in [".zip", ".tar.gz", ".whl"]):
+                print(
+                        f"While building the index for project '{project_name}' found non Python package file '{filename}', which will be ignored.",
+                        file=sys.stderr,
+                        flush=True,
+                )
                 continue
             assert filename.startswith(normalized_project_name + "-")
 
diff --git a/issue_dispatch.sh b/issue_dispatch.sh
deleted file mode 100644
index f6c6ce1..0000000
--- a/issue_dispatch.sh
+++ /dev/null
@@ -1,24 +0,0 @@
-#!/bin/bash
-
-REPO="test_package_index"
-OWNER="philip-paul-mueller"
-
-SOURCE_REPO="dace"
-SOURCE_ORG="gridtools"
-DEPENDENCY_REF="gt4py-next-integration"
-
-if [ ! -e ".token" ]
-then
-	echo "The file with the token, '.token' does not exist."
-	echo " According to 'https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#create-a-repository-dispatch-event'"
-	echo " a fine grained token with '\"Contents\" repository permissions (write)' is needed."
-	exit 1
-fi
-
-curl -L -v \
-  -X POST \
-  -H "Accept: application/vnd.github+json" \
-  -H "Authorization: Bearer $(cat .token)" \
-  -H "X-GitHub-Api-Version: 2022-11-28" \
-  https://api.github.com/repos/${OWNER}/${REPO}/dispatches \
-  -d '{"event_type":"update_package_index","client_payload":{"source_repo":"'"${SOURCE_REPO}"'","source_org":"'"${SOURCE_ORG}"'","dependency_ref":"'"${DEPENDENCY_REF}"'"}}'
diff --git a/issue_update.sh b/issue_update.sh
new file mode 100644
index 0000000..39db312
--- /dev/null
+++ b/issue_update.sh
@@ -0,0 +1,107 @@
+#!/bin/bash
+
+# Location of the repo that hosts the actuall index.
+INDEX_REPO="test_package_index"
+INDEX_ORGANIZATION="philip-paul-mueller"
+SCRIPT_FOLDER="$(dirname "$(realpath "${BASH_SOURCE[0]}")")"
+
+SOURCE_REPO=""
+SOURCE_ORG=""
+DEPENDENCY_REF=""
+
+while [ $# -gt 0 ]
+do
+	ARG="$1"
+	shift
+	case "${ARG}" in
+	  --source-repo)
+		if [ ! -z "${SOURCE_REPO}" ]
+		then
+			echo "Specified '--source-repo' multiple times, first time was '${SOURCE_REPO}', second time was '$1'." >&2
+			exit 2
+		fi
+		SOURCE_REPO="$1"
+		shift
+	  ;;
+
+  	  --source-org|--source-owner)
+		if [ ! -z "${SOURCE_ORG}" ]
+		then
+			echo "Specified '--source-org/owner' multiple times, first time was '${SOURCE_ORG}', second time was '$1'." >&2
+			exit 2
+		fi
+		SOURCE_ORG="$1"
+		shift
+	  ;;
+
+	  --ref|--source-branch)
+		if [ ! -z "${DEPENDENCY_REF}" ]
+		then
+			echo "Specified '--ref' multiple times, first time was '${DEPENDENCY_REF}', second time was '$1'." >&2
+			exit 2
+		fi
+		DEPENDENCY_REF="$1"
+		shift
+	  ;;
+
+	  --help|-h)
+		cat << __EOF__
+Allows to trigger the 'update-python-pkg-index' manually to update the GT4Py specific
+dependencies. In order to work a token must be provided which is assumed to be '.token',
+located along this script.
+The script has the following options:
+  --source-org | --source-owner:  The owner of the repo containing the dependency.
+  --source-repo:  The repo containing the dependency.
+  --source-ref | --ref:  The reference, git entity, from which the package should be build.
+
+To token either needs to have full (write) access to the index repo, i.e. this repo,
+or if it is a fine grained access token it needs to have the '"Contents" repository
+permissions (write)' permission.
+
+__EOF__
+		exit 0
+	  ;;
+
+	  --*)
+		echo "Unknown option '${ARG}'" >&2
+		echo " try using '$0 --help'." >&2
+		exit 3
+	  ;;
+
+	  *)
+		echo "Unknown value '${ARG}'" >&2
+		echo " try using '$0 --help'." >&2
+		exit 4
+	  ;;
+	esac
+done
+
+if [ -z "${SOURCE_ORG}" ]
+then
+	echo "--source-org was not specified." >&2
+	exit 5
+elif [ -z "${SOURCE_REPO}" ]
+then
+	echo "--source-repo was not specified." >&2
+	exit 5
+elif [ -z "${DEPENDENCY_REF}" ]
+then
+	echo "--dependency-ref was not specified." >&2
+	exit 5
+fi
+
+if [ ! -e ".token" ]
+then
+	echo "The file with the token, '.token' does not exist."
+	echo " According to 'https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#create-a-repository-dispatch-event'"
+	echo " a fine grained token with '\"Contents\" repository permissions (write)' is needed."
+	exit 1
+fi
+
+curl -L -v \
+  -X POST \
+  -H "Accept: application/vnd.github+json" \
+  -H "Authorization: Bearer $(cat .token)" \
+  -H "X-GitHub-Api-Version: 2022-11-28" \
+  "https://api.github.com/repos/${INDEX_ORGANIZATION}/${INDEX_REPO}/dispatches" \
+  -d '{"event_type":"update_package_index","client_payload":{"source_repo":"'"${SOURCE_REPO}"'","source_org":"'"${SOURCE_ORG}"'","dependency_ref":"'"${DEPENDENCY_REF}"'"}}'
diff --git a/update-python-pkg-index.yml b/update-python-pkg-index.yml
new file mode 120000
index 0000000..d01b250
--- /dev/null
+++ b/update-python-pkg-index.yml
@@ -0,0 +1 @@
+.github/workflows/update-python-pkg-index.yml
\ No newline at end of file

From 23bce75a9683173c50854becf9e6fdf99e16e721 Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Fri, 21 Nov 2025 11:06:16 +0100
Subject: [PATCH 05/20] Added a reminder.

---
 .github/workflows/update-python-pkg-index.yml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.github/workflows/update-python-pkg-index.yml b/.github/workflows/update-python-pkg-index.yml
index 41f2003..04a374b 100644
--- a/.github/workflows/update-python-pkg-index.yml
+++ b/.github/workflows/update-python-pkg-index.yml
@@ -62,6 +62,10 @@ jobs:
           CI_COMMIT_EMAIL: username@users.noreply.github.com
         run: |
           cd ./index_repo
+
+          # Not fully sure if this check is useful, because it seems that creating a wheel is not reproducible.
+          #  I.e. creating a wheel from a commit and then generating another wheel will result in a "different",
+          #  in terms of its hash, file than the first time.
           if ! git status --porcelain --untracked-files=no ; then
             # There are no changed.
             echo "There were no changes!"

From 1e806c7d451070540743e008c1fb5b59cc77fdad Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Fri, 21 Nov 2025 11:20:14 +0100
Subject: [PATCH 06/20] Implemented an install tester, not yet tested.

---
 .github/workflows/update-python-pkg-index.yml | 26 ++++++++++++++++---
 .gitignore                                    |  1 +
 README.md                                     |  4 +--
 3 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/update-python-pkg-index.yml b/.github/workflows/update-python-pkg-index.yml
index 04a374b..035c0f9 100644
--- a/.github/workflows/update-python-pkg-index.yml
+++ b/.github/workflows/update-python-pkg-index.yml
@@ -47,12 +47,32 @@ jobs:
         shell: bash
         run: |
           DEPENDENCY_REPO="${PWD}/${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}"
-          DIST_FOLDER="${PWD}/index_repo/${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}"
+          PACKAGE_BUILD_FOLDER="${PWD}/index_repo/build"
 
-          # TODO: Test if we can install it.
           cd "${DEPENDENCY_REPO}"
           python -m pip install build --user
-          python -m build --wheel --outdir "${DIST_FOLDER}"
+          python -m build --wheel --outdir "${PACKAGE_BUILD_FOLDER}"
+
+      - name: Test the distribution file.
+        shell: bash
+        run: |
+          PACKAGE_BUILD_FOLDER="${PWD}/index_repo/build"
+          DESTINATION_FOLDER="${PWD}/index_repo/${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}"
+          mkdir -p "${DESTINATION_FOLDER}"
+
+          readarray -t -d "" PACKAGE_FILES  < <(find "${PACKAGE_BUILD_FOLDER}" -type f -print0)
+          for I in ${!PACKAGE_FILES[@]}
+          do
+            PACKAGE_FILE="${PACKAGE_FILES[$I]}"
+            pip install --force-reinstall --upgrade --no-deps "${PACKAGE_FILE}"
+            if [ $? -ne 0 ]
+            then
+              echo "Failed to install package '${PACKAGE_FILE}'"
+              exit 3
+            fi
+            echo "Successfully tested '${PACKAGE_FILE}'"
+            cp -t "${DESTINATION_FOLDER}" "${PACKAGE_FILE}"
+          done
 
       - name: Rescan the package index and update the static `index.html` files.
         shell: bash
diff --git a/.gitignore b/.gitignore
index d20209c..993a092 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 .token*
+build/
diff --git a/README.md b/README.md
index b3f72e1..a6a46a9 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,7 @@ The repo is intended to work fully automatically, orchestrated by GitHub actions
 This is the main workflow, in short it does:
 - Pulls the repo, whose package should be updated.
 - Creates a wheel from the repo that has been pulled.
+- Tests if the wheel can be installed.
 - Updated the package index, i.e. regenerates the `index.html` files, for this `generator.py` is used.
 - Creates a commit containing the updated indexes and the generated wheel.
 - Pushes the new commit directly to `main`.
@@ -39,6 +40,3 @@ In order for the _depending_ repo to issue an update request an access token is
 This can either be a normal (classic) access token, that needs to grant read access to the repository.
 The other possibility is to use a fine grained access token, in which case only the '"Contents" repository permissions (write)' permission has to be granted.
 
-
-# TODO:
-- Test if the wheel can be installed.

From aa9a713df0be1d3e918e1cffb42c9272fae5ae88 Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Fri, 21 Nov 2025 13:27:49 +0100
Subject: [PATCH 07/20] Strange world we are living in.

---
 .github/workflows/update-python-pkg-index.yml | 3 +++
 README.md                                     | 5 +++++
 2 files changed, 8 insertions(+)

diff --git a/.github/workflows/update-python-pkg-index.yml b/.github/workflows/update-python-pkg-index.yml
index 035c0f9..1ab3b06 100644
--- a/.github/workflows/update-python-pkg-index.yml
+++ b/.github/workflows/update-python-pkg-index.yml
@@ -17,6 +17,9 @@ on:
         description: 'Reference that in the dependency repo that should be checked out and turned into a dependency.'
         required: true
         type: string
+  # We need this until this file is not in `main`, without it the web interface will not pick it up.
+  #  See https://stackoverflow.com/a/71057825
+  pull_request:
 
 jobs:
   update-index:
diff --git a/README.md b/README.md
index a6a46a9..315e5e9 100644
--- a/README.md
+++ b/README.md
@@ -40,3 +40,8 @@ In order for the _depending_ repo to issue an update request an access token is
 This can either be a normal (classic) access token, that needs to grant read access to the repository.
 The other possibility is to use a fine grained access token, in which case only the '"Contents" repository permissions (write)' permission has to be granted.
 
+# TODO:
+- Install in DaCe
+- Install in GHEX
+- Configure the page to use `main` as source.
+

From 996a3434bc7271bcfc91975d53c7da330d780f97 Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Fri, 21 Nov 2025 13:31:19 +0100
Subject: [PATCH 08/20] Can we remove that hack now?

---
 .github/workflows/update-python-pkg-index.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/update-python-pkg-index.yml b/.github/workflows/update-python-pkg-index.yml
index 1ab3b06..a994b02 100644
--- a/.github/workflows/update-python-pkg-index.yml
+++ b/.github/workflows/update-python-pkg-index.yml
@@ -19,7 +19,7 @@ on:
         type: string
   # We need this until this file is not in `main`, without it the web interface will not pick it up.
   #  See https://stackoverflow.com/a/71057825
-  pull_request:
+  #pull_request:
 
 jobs:
   update-index:

From 6beac8c9629427534b343fd86c721ff1318a754c Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Fri, 21 Nov 2025 14:43:21 +0100
Subject: [PATCH 09/20] Be a bit more verbose, good for debugging.

---
 .github/workflows/update-python-pkg-index.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/update-python-pkg-index.yml b/.github/workflows/update-python-pkg-index.yml
index a994b02..696b74f 100644
--- a/.github/workflows/update-python-pkg-index.yml
+++ b/.github/workflows/update-python-pkg-index.yml
@@ -31,6 +31,7 @@ jobs:
           echo "source_repo: ${{ inputs.source_repo == '' && github.event.client_payload.source_repo || inputs.source_repo }}"
           echo "source_org:  ${{ inputs.source_org == '' && github.event.client_payload.source_org || inputs.source_org }}"
           echo "dep_ref:     ${{ inputs.dependency_ref == '' && github.event.client_payload.dependency_ref || inputs.dependency_ref }}"
+          echo "payload:     ${{ toJson(github.event.client_payload) }}"
 
       - name: Checkout the `main` branch of the Python package index.
         uses: actions/checkout@v4

From f81d893f6e615543c2e54472919526721b95f7a2 Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Fri, 21 Nov 2025 14:43:50 +0100
Subject: [PATCH 10/20] Added the thing that we need to run it.

---
 README.md                         |  9 +++++--
 update_workflows/dace-updater.yml | 40 +++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 2 deletions(-)
 create mode 100644 update_workflows/dace-updater.yml

diff --git a/README.md b/README.md
index 315e5e9..dd45624 100644
--- a/README.md
+++ b/README.md
@@ -30,9 +30,14 @@ It is usually run by by the workflow automatically.
 A simple script that allows to issue a manual remote update of the index.
 For more information please see its help output.
 
+## `update_workflows`
+This folder contains the workflows that must be installed into the repos containing the dependency.
 
-# How to install a dependency
-TBA:
+### DaCe
+For DaCe the `dace-updater.yml` must be added to the DaCe repo.
+It listens for pushes to tags `__gt4py-next-integration_*`, i.e. the ones that we use to tag our releases.
+
+**TODO:** Figuring out where it should life, because I am sure it must life in `main`.
 
 
 ## Token
diff --git a/update_workflows/dace-updater.yml b/update_workflows/dace-updater.yml
new file mode 100644
index 0000000..916341b
--- /dev/null
+++ b/update_workflows/dace-updater.yml
@@ -0,0 +1,40 @@
+name: Inform the Python package index about a new DaCe release.
+
+on:
+  #push:
+    # Only run once a new tag has been created.
+    # TODO: Make sure that the tag is passed to the index update workflow.
+    #tags:
+      #- __gt4py-next-integration_*
+
+  # We need this until this file is not in `main`, without it the web interface will not pick it up.
+  #  See https://stackoverflow.com/a/71057825
+  pull_request:
+
+  # For some reasons this does not work, so it can not be triggered manually.
+  workflow_dispatch:
+
+jobs:
+  update-dace:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Inform Index
+        shell: bash
+        run: |
+          INDEX_ORGANIZATION="gridtools"
+          INDEX_REPO="python-pkg-index"
+
+          # We are using `github.sha` here to be sure that we transmit an identifier to the index
+          #  that can be checked out. Before we used `github.ref_name` but got strange results
+          #  with it.
+          DEPENDENCY_REF="${{ github.sha }}"
+          SOURCE_REPO="dace"
+          SOURCE_OWNER="gridtools"
+
+          curl -L -v \
+            -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer ${{ secrets.PKG_UPDATE_TOKEN }}" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            "https://api.github.com/repos/${INDEX_ORGANIZATION}/${INDEX_REPO}/dispatches" \
+            -d '{"event_type":"update_package_index","client_payload":{"source_repo":"'"${SOURCE_REPO}"'","source_org":"'"${SOURCE_OWNER}"'","dependency_ref":"'"${DEPENDENCY_REF}"'"}}'

From ec8db9a9a3bca14aa582f5cdeeda0615faea0e23 Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Fri, 21 Nov 2025 15:02:13 +0100
Subject: [PATCH 11/20] Added more documentation to it.

---
 .github/workflows/update-python-pkg-index.yml | 4 ++++
 README.md                                     | 4 ++++
 update_workflows/dace-updater.yml             | 9 ++++++---
 3 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/update-python-pkg-index.yml b/.github/workflows/update-python-pkg-index.yml
index 696b74f..bd5de99 100644
--- a/.github/workflows/update-python-pkg-index.yml
+++ b/.github/workflows/update-python-pkg-index.yml
@@ -3,6 +3,9 @@ name: Updates the Python package index upon an event.
 on:
   repository_dispatch:
     types: [update_package_index]
+
+  # According to the [documentation](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow#configuring-a-workflow-to-run-manually)
+  # it is only possible to trigger a workflow manually, if it is located in the default branch.
   workflow_dispatch:
     inputs:
       source_repo:
@@ -17,6 +20,7 @@ on:
         description: 'Reference that in the dependency repo that should be checked out and turned into a dependency.'
         required: true
         type: string
+
   # We need this until this file is not in `main`, without it the web interface will not pick it up.
   #  See https://stackoverflow.com/a/71057825
   #pull_request:
diff --git a/README.md b/README.md
index dd45624..ed892f6 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,10 @@ In either case some information have to be provided:
 - The owner (user or organization) that owns the repo, generally referred to as "source owner".
 - The branch of the repo from which a Python package should be created, generally referred to as "dependency ref".
 
+> According to the [documentation](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#repository_dispatch) the
+> `repository_dispatch` trigger (the one that is used such that _other_ repo can start the update) only works when
+> the workflow file is located on the default branch!
+
 ## `generator.py`
 Script for updating the static pages.
 It works by scanning subfolders, currently `dace` and `ghex`, and creates an index based on all Python packages it founds in them.
diff --git a/update_workflows/dace-updater.yml b/update_workflows/dace-updater.yml
index 916341b..4f7c72e 100644
--- a/update_workflows/dace-updater.yml
+++ b/update_workflows/dace-updater.yml
@@ -1,17 +1,20 @@
 name: Inform the Python package index about a new DaCe release.
 
 on:
+  # According to the [documentation](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#push)
+  # this event will trigger even when the workflow file is not located on the default branch.
   #push:
     # Only run once a new tag has been created.
     # TODO: Make sure that the tag is passed to the index update workflow.
     #tags:
       #- __gt4py-next-integration_*
 
-  # We need this until this file is not in `main`, without it the web interface will not pick it up.
+  # Define this to ensure that it runs and is visible in the settings.
   #  See https://stackoverflow.com/a/71057825
-  pull_request:
+  #pull_request:
 
-  # For some reasons this does not work, so it can not be triggered manually.
+  # According to the [documentation](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow#configuring-a-workflow-to-run-manually)
+  # it is only possible to trigger a workflow manually, if it is located in the default branch.
   workflow_dispatch:
 
 jobs:

From 27963af9e3ba11623816a8ac0abd3cc609591011 Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Fri, 21 Nov 2025 15:47:09 +0100
Subject: [PATCH 12/20] Updated the readme with the newest state.

---
 README.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ed892f6..70a9a82 100644
--- a/README.md
+++ b/README.md
@@ -40,8 +40,10 @@ This folder contains the workflows that must be installed into the repos contain
 ### DaCe
 For DaCe the `dace-updater.yml` must be added to the DaCe repo.
 It listens for pushes to tags `__gt4py-next-integration_*`, i.e. the ones that we use to tag our releases.
-
-**TODO:** Figuring out where it should life, because I am sure it must life in `main`.
+There is an [_experimental_ branch](https://github.com/GridTools/dace/pull/12) that tests the workflow using the [development index](https://github.com/philip-paul-mueller/test_package_index).
+It kind of works, however, currently only pushes related to the branch itself are detected, i.e. the branch that contains the workflow file.
+This means, that the workflow file must be included inside `gt4py-next-integration` branch, that is used to deploy the thing, which is not so nice.   
+As an experiment, I changed the defualt branch from `main` to the experimental one, without success, but it might be due to the mentioned "unintended side effects" that a popup was informing me.
 
 
 ## Token

From 8d051311e83604d45637b2a6fb5c6adbd3523fbe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Philip=20M=C3=BCller?=
 <147368808+philip-paul-mueller@users.noreply.github.com>
Date: Mon, 1 Dec 2025 06:55:22 +0100
Subject: [PATCH 13/20] Update generator.py
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Enrique González Paredes <enriqueg@cscs.ch>
---
 generator.py | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/generator.py b/generator.py
index d691e5a..8edeada 100644
--- a/generator.py
+++ b/generator.py
@@ -7,6 +7,9 @@
 import re
 import sys
 
+#: The header for a html page.
+#: It contains the opening `<body>` tag and has the `Titel` interpolation.
+"""
 HTML_HEADER: Final[str] = """\
 <!DOCTYPE HTML>
 <html>
@@ -18,10 +21,6 @@
     <body>
     <h1>{Title}</h1>
 """
-"""The header for a html page.
-
-It contains the opening `<body>` tag and has the `Titel` interpolation.
-"""
 
 HTML_FOOTER: Final[str] = """\
     </body>

From 3db0e93b709afc17b3e257f5c37125681ef88b17 Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Mon, 1 Dec 2025 06:59:00 +0100
Subject: [PATCH 14/20] Formatting.

---
 generator.py | 40 +++++++++++++++++++---------------------
 1 file changed, 19 insertions(+), 21 deletions(-)

diff --git a/generator.py b/generator.py
index 8edeada..9a5090f 100644
--- a/generator.py
+++ b/generator.py
@@ -9,7 +9,6 @@
 
 #: The header for a html page.
 #: It contains the opening `<body>` tag and has the `Titel` interpolation.
-"""
 HTML_HEADER: Final[str] = """\
 <!DOCTYPE HTML>
 <html>
@@ -22,14 +21,13 @@
     <h1>{Title}</h1>
 """
 
+#: Contains the footer of an html page.
+#: This includes the closing `</body>` tag.
 HTML_FOOTER: Final[str] = """\
     </body>
 </html>
 """
-"""Contains the footer of an html page.
 
-This includes the closing `</body>` tag.
-"""
 
 def normalize_name(name: str) -> bool:
     """Normalize the project name according to the rules in PEP503."""
@@ -37,14 +35,14 @@ def normalize_name(name: str) -> bool:
 
 
 def write_project_index(
-        base_folder: pathlib.Path,
-        project_name: str,
+    base_folder: pathlib.Path,
+    project_name: str,
 ) -> int:
     # Project folder must exists because we assume that the files are located inside.
     project_folder = base_folder / project_name
     if not project_folder.is_dir():
         raise NotADirectoryError(
-                f"Expected that the project folder `{project_folder}` for project `{project_name}` exists."
+            f"Expected that the project folder `{project_folder}` for project `{project_name}` exists."
     )
 
     found_packages = 0
@@ -56,9 +54,9 @@ def write_project_index(
             filename = file.name
             if filename.startswith(".") or not any(filename.endswith(ext) for ext in [".zip", ".tar.gz", ".whl"]):
                 print(
-                        f"While building the index for project '{project_name}' found non Python package file '{filename}', which will be ignored.",
-                        file=sys.stderr,
-                        flush=True,
+                    f"While building the index for project '{project_name}' found non Python package file '{filename}', which will be ignored.",
+                    file=sys.stderr,
+                    flush=True,
                 )
                 continue
             assert filename.startswith(normalized_project_name + "-")
@@ -71,7 +69,7 @@ def write_project_index(
             #  is not need for fancy processing of the file name. Furthermore, we assume that
             #  the file names have the correct normalized name and version.
             index.write(
-                    f'\t\t<a href="{filename}#sha256={digest.hexdigest()}">{filename}</a> </br>\n'.replace("\t", "    ")
+                f'\t\t<a href="{filename}#sha256={digest.hexdigest()}">{filename}</a> </br>\n'.replace("\t", "    ")
             )
             found_packages += 1
         index.write(HTML_FOOTER)
@@ -80,8 +78,8 @@ def write_project_index(
 
 
 def write_package_index(
-        base_folder: pathlib.Path,
-        packages: Sequence[str],
+    base_folder: pathlib.Path,
+    packages: Sequence[str],
 ) -> None:
 
     with open(base_folder / "index.html", "wt") as index:
@@ -92,9 +90,9 @@ def write_package_index(
             normalized_project_name = normalize_name(project_name)
             if not project_folder.is_dir():
                 print(
-                        f"There is not folder associated to the project `{project_name}`, skipping it.",
-                        flush=True,
-                        file=sys.stderr,
+                    f"There is not folder associated to the project `{project_name}`, skipping it.",
+                    flush=True,
+                    file=sys.stderr,
                 )
                 continue
 
@@ -105,9 +103,9 @@ def write_package_index(
                 # Consider no packages not as an error, only output a warning.
                 # TODO: Consider removing the folder.
                 print(
-                        f"No packages for project `{project_name}` could be located.",
-                        flush=True,
-                        file=sys.stderr,
+                    f"No packages for project `{project_name}` could be located.",
+                    flush=True,
+                    file=sys.stderr,
                 )
                 continue
 
@@ -118,6 +116,6 @@ def write_package_index(
 
 if __name__ == "__main__":
     write_package_index(
-            base_folder=pathlib.Path(__file__).parent,
-            packages=["dace", "ghex"],
+        base_folder=pathlib.Path(__file__).parent,
+        packages=["dace", "ghex"],
     )

From 00b84692f64914ff859aa2e1f0ef52051de7f8ab Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Mon, 1 Dec 2025 07:03:35 +0100
Subject: [PATCH 15/20] What is going on.

---
 index.html | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 index.html

diff --git a/index.html b/index.html
new file mode 100644
index 0000000..b50178a
--- /dev/null
+++ b/index.html
@@ -0,0 +1,11 @@
+<!DOCTYPE HTML>
+<html>
+    <head>
+        <title>Custom Package Index for GT4Py</title>
+        <meta charset="UTF-8" />
+    </head>
+
+    <body>
+    <h1>Custom Package Index for GT4Py</h1>
+    </body>
+</html>

From aeea91eeb6681330d48e9c1085c14bd5255674a5 Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Mon, 1 Dec 2025 07:06:43 +0100
Subject: [PATCH 16/20] Ensured that the folder existed.

---
 dace/.gitkeep | 0
 ghex/.gitkeep | 0
 2 files changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 dace/.gitkeep
 create mode 100644 ghex/.gitkeep

diff --git a/dace/.gitkeep b/dace/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/ghex/.gitkeep b/ghex/.gitkeep
new file mode 100644
index 0000000..e69de29

From 9b372688468bf49ca0b2f5bce7d3d5cba443908e Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Mon, 1 Dec 2025 07:26:44 +0100
Subject: [PATCH 17/20] Updated the readme.

---
 README.md | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 70a9a82..7248eac 100644
--- a/README.md
+++ b/README.md
@@ -3,8 +3,10 @@ This repo hosts the custom packages that are needed to use GT4Py, these currentl
 - [GridTools/dace](https://github.com/GridTools/dace), currently only for the `next`.
 - [ghex-org/GHEX](https://github.com/ghex-org/GHEX)
 
+
 # Usage
 The repo is intended to work fully automatically, orchestrated by GitHub actions.
+See also the design section below.
 
 ## Workflow `update-python-pkg-index.yml`
 This is the main workflow, in short it does:
@@ -36,6 +38,7 @@ For more information please see its help output.
 
 ## `update_workflows`
 This folder contains the workflows that must be installed into the repos containing the dependency.
+These workflows then triggers the update chain.
 
 ### DaCe
 For DaCe the `dace-updater.yml` must be added to the DaCe repo.
@@ -43,14 +46,23 @@ It listens for pushes to tags `__gt4py-next-integration_*`, i.e. the ones that w
 There is an [_experimental_ branch](https://github.com/GridTools/dace/pull/12) that tests the workflow using the [development index](https://github.com/philip-paul-mueller/test_package_index).
 It kind of works, however, currently only pushes related to the branch itself are detected, i.e. the branch that contains the workflow file.
 This means, that the workflow file must be included inside `gt4py-next-integration` branch, that is used to deploy the thing, which is not so nice.   
-As an experiment, I changed the defualt branch from `main` to the experimental one, without success, but it might be due to the mentioned "unintended side effects" that a popup was informing me.
-
+As an experiment, I changed the default branch from `main` to the experimental one, without success, but it might be due to the mentioned "unintended side effects" that a popup was informing me.
 
 ## Token
 In order for the _depending_ repo to issue an update request an access token is needed.
 This can either be a normal (classic) access token, that needs to grant read access to the repository.
 The other possibility is to use a fine grained access token, in which case only the '"Contents" repository permissions (write)' permission has to be granted.
 
+
+# Design and Working
+The index works currently in "pull mode".
+This means that the dependent repos, i.e. DaCe or GHEX, informs the index (this repo), that a new version is available.
+The index will then download the depending repo, build the Python package and update the html pages.
+
+However, it would be conceptually simpler, if the index is passive, i.e. if the dependent repos would build the Python package themself and push it to the index.
+This design, "push mode", should become the new operation mode in the future.
+
+
 # TODO:
 - Install in DaCe
 - Install in GHEX

From cc23b046eaf336690a443bb72cb3353798effe9f Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Mon, 1 Dec 2025 09:12:09 +0100
Subject: [PATCH 18/20] Updated the README.md.

---
 README.md | 38 +++++++++++++++++++++++++-------------
 1 file changed, 25 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 7248eac..fc4f940 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,6 @@ This repo hosts the custom packages that are needed to use GT4Py, these currentl
 
 # Usage
 The repo is intended to work fully automatically, orchestrated by GitHub actions.
-See also the design section below.
 
 ## Workflow `update-python-pkg-index.yml`
 This is the main workflow, in short it does:
@@ -27,31 +26,44 @@ In either case some information have to be provided:
 > `repository_dispatch` trigger (the one that is used such that _other_ repo can start the update) only works when
 > the workflow file is located on the default branch!
 
+
 ## `generator.py`
 Script for updating the static pages.
 It works by scanning subfolders, currently `dace` and `ghex`, and creates an index based on all Python packages it founds in them.
 It is usually run by by the workflow automatically.
 
+
 ## `issue_update.sh`
 A simple script that allows to issue a manual remote update of the index.
 For more information please see its help output.
 
+
 ## `update_workflows`
-This folder contains the workflows that must be installed into the repos containing the dependency.
-These workflows then triggers the update chain.
+This folder contains the workflows that must be installed into the repos containing the dependency, these workflows then triggers the update chain.
+Here are the steps that are needed to install them.
+
+
+### Token
+The first step is to create an access token for the package index.
+It is recommended that a [fine grained access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens) is used.
+The token should only grant access to the index repo and must have the '"Contents" repository permissions (write)' permission.
+
+Then you must install the token in the depending repo, the updater workflow expect the nae `PKG_UPDATE_TOKEN`.
+
+
+### General Process of Installing the Workflow
+The installations of workflows is not straight forward.
+First you must activate (uncomment) the `pull_request` trigger and push it.
+The net effect is that it will run once and GitHub will pick it up then.
+Afterwards you have to disable that trigger again.
+
 
 ### DaCe
 For DaCe the `dace-updater.yml` must be added to the DaCe repo.
-It listens for pushes to tags `__gt4py-next-integration_*`, i.e. the ones that we use to tag our releases.
-There is an [_experimental_ branch](https://github.com/GridTools/dace/pull/12) that tests the workflow using the [development index](https://github.com/philip-paul-mueller/test_package_index).
-It kind of works, however, currently only pushes related to the branch itself are detected, i.e. the branch that contains the workflow file.
-This means, that the workflow file must be included inside `gt4py-next-integration` branch, that is used to deploy the thing, which is not so nice.   
-As an experiment, I changed the default branch from `main` to the experimental one, without success, but it might be due to the mentioned "unintended side effects" that a popup was informing me.
-
-## Token
-In order for the _depending_ repo to issue an update request an access token is needed.
-This can either be a normal (classic) access token, that needs to grant read access to the repository.
-The other possibility is to use a fine grained access token, in which case only the '"Contents" repository permissions (write)' permission has to be granted.
+Follow the steps above and place it in its [own dedicated PR](https://github.com/GridTools/dace/pull/12).
+Note that it only works if this PR is is included in the `gt4py-next-integration` branch, see [these instructions](https://github.com/GridTools/dace/pull/1).
+
+The workflow listens for pushes to tags for the form `__gt4py-next-integration_*`, if such a push is detected, it will then inform the index repo about the new version.
 
 
 # Design and Working

From 6a124a8561741135a715040860091c566259e49a Mon Sep 17 00:00:00 2001
From: Philip Mueller <philip.mueller@cscs.ch>
Date: Mon, 1 Dec 2025 10:17:46 +0100
Subject: [PATCH 19/20] Made some updates.

---
 update_workflows/dace-updater.yml | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/update_workflows/dace-updater.yml b/update_workflows/dace-updater.yml
index 4f7c72e..c33bdd1 100644
--- a/update_workflows/dace-updater.yml
+++ b/update_workflows/dace-updater.yml
@@ -1,20 +1,18 @@
 name: Inform the Python package index about a new DaCe release.
 
 on:
-  # According to the [documentation](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#push)
-  # this event will trigger even when the workflow file is not located on the default branch.
-  #push:
-    # Only run once a new tag has been created.
-    # TODO: Make sure that the tag is passed to the index update workflow.
-    #tags:
-      #- __gt4py-next-integration_*
+  # Trigger for all pushes to tags matching this pattern
+  push:
+    tags:
+      - __gt4py-next-integration_*
 
-  # Define this to ensure that it runs and is visible in the settings.
+  # To "install" this workflow you must enable this trigger, such that the workflow runs at least one.
+  #  You should also disable any processing such that no commit in the index repo is performed.
   #  See https://stackoverflow.com/a/71057825
   #pull_request:
 
-  # According to the [documentation](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow#configuring-a-workflow-to-run-manually)
-  # it is only possible to trigger a workflow manually, if it is located in the default branch.
+  # Allows to trigger the update manually.
+  # NOTE: Is only possible if the workflow file is located on the default and the branch where it should run on.
   workflow_dispatch:
 
 jobs:

From 9e28a26d880cf939022537c13fc352a817ff5767 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Philip=20M=C3=BCller?=
 <147368808+philip-paul-mueller@users.noreply.github.com>
Date: Tue, 2 Dec 2025 16:29:22 +0100
Subject: [PATCH 20/20] Update index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Enrique González Paredes <enriqueg@cscs.ch>
---
 index.html | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/index.html b/index.html
index b50178a..6f995d3 100644
--- a/index.html
+++ b/index.html
@@ -1,11 +1,11 @@
 <!DOCTYPE HTML>
 <html>
     <head>
-        <title>Custom Package Index for GT4Py</title>
+        <title>Custom Python Package Index for the GridTools organization</title>
         <meta charset="UTF-8" />
     </head>
 
     <body>
-    <h1>Custom Package Index for GT4Py</h1>
+    <h1>Custom Python Package Index for the GridTools organization</h1>
     </body>
 </html>