Initial implementation: aptly container image, Compose stacks, Helm chart, and Gitea Actions pipelines

Provides a self-contained, containerized aptly (Debian repo manager)
stack with independently releasable image and Helm chart versions.

- images/: aptly-server (aptly built from source, cross-compiled) and
  aptly-deb-builder (nfpm + dpkg-buildpackage) container images
- rootfs/: shared aptly-init/aptly-reconcile/aptly-push/aptly-pack
  scripts consumed identically by Compose and the Helm chart, driven
  by one declarative state.yaml contract
- compose/: test (ephemeral, open) and production docker-compose
  stacks with an nginx read/auth sidecar
- charts/aptly/: aptly-native Helm chart covering every security
  posture from fully open to authenticated read+write, Ingress and
  Gateway API support (usable in parallel for migration scenarios),
  metrics, and declarative repo/mirror/publish reconciliation via a
  Helm hook
- .gitea/workflows/: CI (lint, template, kubeconform, E2E smoke test)
  plus separately tagged image (image/v*) and chart (chart/v*)
  releases, weekly rebuilds, and a preflight workflow validating the
  runner's Docker/Helm-OCI capabilities
- pubkeys/: RSA chart-signing key for Helm --sign / Artifact Hub's
  signKey annotation (Helm can't verify Ed25519 keys)
- docs/, README.md, charts/aptly/README.md: usage, security, and
  versioning documentation

.gitea/workflows/ci.yaml

@@ -0,0 +1,77 @@
+name: CI
+# Runs on every PR and every push to main. The smoke-test job is the actual
+# merge gate for this repo — it proves pack -> push -> publish -> apt-get
+# works, not just that files parse. See tests/smoke-test.sh.
+#
+# paths-ignore + bot commits carrying [skip ci] (see release-image.yaml)
+# exist to break the automation loop: an image release commits a new
+# appVersion to main, which would otherwise re-trigger this workflow, which
+# has nothing new to check.
+on:
+  pull_request: {}
+  push:
+    branches: [main]
+    paths-ignore:
+      - 'charts/aptly/Chart.yaml'
+      - 'CHANGELOG.md'
+
+concurrency:
+  group: ci-${{ gitea.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: hadolint (aptly-server)
+        uses: hadolint/hadolint-action@v3.1.0
+        with:
+          dockerfile: images/aptly-server/Dockerfile
+      - name: hadolint (aptly-deb-builder)
+        uses: hadolint/hadolint-action@v3.1.0
+        with:
+          dockerfile: images/aptly-deb-builder/Dockerfile
+
+      - name: shellcheck
+        run: |
+          docker run --rm -v "$PWD:/work" -w /work koalaman/shellcheck:stable -x \
+            rootfs/usr/local/bin/aptly-* rootfs/usr/local/bin/lib/common.sh tests/smoke-test.sh
+
+      - uses: azure/setup-helm@v4.3.0
+        with:
+          version: ${{ vars.HELM_VERSION || '3.16.4' }}
+      - name: helm lint
+        run: helm lint charts/aptly
+      - name: helm template (every ci/*.yaml values file, plus defaults)
+        run: |
+          set -e
+          helm template test charts/aptly > /tmp/rendered-defaults.yaml
+          for f in charts/aptly/ci/*.yaml; do
+            helm template test charts/aptly -f "$f" > "/tmp/rendered-$(basename "$f" .yaml).yaml"
+          done
+      - name: kubeconform
+        run: |
+          docker run --rm -v /tmp:/tmp ghcr.io/yannh/kubeconform:latest \
+            -summary -strict -kubernetes-version 1.29.0 \
+            -schema-location default \
+            -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
+            /tmp/rendered-*.yaml
+      - name: fail-guard regression check (proxy.enabled=false + Ingress/Gateway + non-open preset must abort)
+        run: |
+          if helm template test charts/aptly --set proxy.enabled=false --set ingress.enabled=true \
+               --set ingress.repo.host=x.example.com >/tmp/should-fail.yaml 2>&1; then
+            echo "::error::expected `helm template` to fail on proxy.enabled=false + ingress.enabled (fail-guard regression)"; exit 1
+          fi
+          if helm template test charts/aptly --set proxy.enabled=false --set gateway.enabled=true \
+               --set 'gateway.parentRefs[0].name=x' >/tmp/should-fail2.yaml 2>&1; then
+            echo "::error::expected `helm template` to fail on proxy.enabled=false + gateway.enabled (fail-guard regression)"; exit 1
+          fi
+
+  smoke-test:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run the end-to-end smoke test
+        run: ./tests/smoke-test.sh

.gitea/workflows/preflight.yaml

@@ -0,0 +1,105 @@
+name: Preflight
+# Manual, one-shot verification that the runner can actually do everything
+# the release workflows assume: build a container image, emulate a foreign
+# architecture, push to this Gitea instance's registry, push a Helm chart via
+# OCI, and reach the Issues API. None of the four existing Gitea Actions
+# workflows in this org build a container image before this repo — so none
+# of that is proven, only assumed. Run this BEFORE relying on release-image.yaml
+# or rebuild.yaml, and again after any Gitea/runner upgrade.
+#
+# See docs/operations.md for the escalation ladder if any job here fails.
+on:
+  workflow_dispatch: {}
+
+jobs:
+  docker-build:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - name: Build aptly-server for the native arch only (no push)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: images/aptly-server/Dockerfile
+          push: false
+          tags: preflight/aptly-server:local
+
+  qemu-multiarch:
+    runs-on: ubuntu-22.04
+    needs: docker-build
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+      - name: Build for linux/amd64,linux/arm64 (no push)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: images/aptly-server/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: false
+
+  registry-push:
+    runs-on: ubuntu-22.04
+    needs: qemu-multiarch
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify registry secrets are set
+        run: |
+          test -n "${{ secrets.REGISTRY_USER }}" || { echo "::error::REGISTRY_USER is not set"; exit 1; }
+          test -n "${{ secrets.REGISTRY_TOKEN }}" || { echo "::error::REGISTRY_TOKEN (a Personal Access Token with write:package) is not set. GITEA_TOKEN cannot authorize package pushes on Gitea — see docs/operations.md."; exit 1; }
+      - uses: docker/login-action@v3
+        with:
+          registry: git.morlana.online
+          username: ${{ secrets.REGISTRY_USER }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+      - name: Push a throwaway multi-arch tag
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: images/aptly-server/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: git.morlana.online/f.weber/aptly:preflight-${{ gitea.sha }}
+      - name: Verify the manifest list has both platforms
+        run: |
+          docker buildx imagetools inspect git.morlana.online/f.weber/aptly:preflight-${{ gitea.sha }}
+
+  helm-oci-push:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: azure/setup-helm@v4.3.0
+        with:
+          version: ${{ vars.HELM_VERSION || '3.16.4' }}
+      - name: helm registry login
+        run: |
+          echo "${{ secrets.REGISTRY_TOKEN }}" | helm registry login git.morlana.online \
+            --username "${{ secrets.REGISTRY_USER }}" --password-stdin
+      - name: Package and push a throwaway chart version
+        run: |
+          helm package charts/aptly --version 0.0.0-preflight --app-version preflight
+          helm push aptly-0.0.0-preflight.tgz oci://git.morlana.online/f.weber
+      - name: Verify it is pullable
+        run: |
+          helm show chart oci://git.morlana.online/f.weber/aptly --version 0.0.0-preflight
+
+  issues-api:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Open and close a test issue (proves rebuild.yaml's failure alert path)
+        env:
+          GITEA_API: https://git.morlana.online/api/v1
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          issue_number=$(curl -fsS -X POST "${GITEA_API}/repos/${{ gitea.repository }}/issues" \
+            -H "Authorization: token ${TOKEN}" -H "Content-Type: application/json" \
+            -d '{"title":"[preflight] issues API check","body":"Created by preflight.yaml — safe to close/delete."}' \
+            | jq -r '.number')
+          curl -fsS -X PATCH "${GITEA_API}/repos/${{ gitea.repository }}/issues/${issue_number}" \
+            -H "Authorization: token ${TOKEN}" -H "Content-Type: application/json" \
+            -d '{"state":"closed"}' >/dev/null
+          echo "opened and closed issue #${issue_number}"

.gitea/workflows/rebuild.yaml

@@ -0,0 +1,71 @@
+name: Weekly rebuild
+# Bumps the image revision (1.6.3-1 -> 1.6.3-2) and tags it, which triggers
+# release-image.yaml — the mechanism that pulls in Debian base-image security
+# patches even between aptly releases. This is the "aptly keeps itself
+# current" half that isn't a Renovate PR: it needs zero human action to land.
+#
+# Gitea's `schedule` trigger only fires from the default branch — a branch
+# rename silently disables this. Because Gitea Actions only implements
+# always() among the status-check expressions (not success()/failure()),
+# failure handling below uses `continue-on-error` + a status file instead of
+# `if: failure()`.
+on:
+  schedule:
+    - cron: '17 3 * * 1'
+  workflow_dispatch: {}
+
+jobs:
+  bump-revision:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Find the latest image tag and compute the next revision
+        id: next
+        continue-on-error: true
+        run: |
+          set -euo pipefail
+          latest="$(git tag --list 'image/v*' --sort=-v:refname | head -1)"
+          if [[ -z "$latest" ]]; then
+            echo "::error::no existing image/v* tag found — cut one manually first (see docs/versioning.md)"
+            exit 1
+          fi
+          version_rev="${latest#image/v}"
+          version="${version_rev%-*}"
+          revision="${version_rev##*-}"
+          next_revision=$(( revision + 1 ))
+          echo "next_tag=image/v${version}-${next_revision}" >> "$GITEA_OUTPUT"
+          echo "latest_tag=${latest}" >> "$GITEA_OUTPUT"
+
+      - name: Stale-rebuild check (fires regardless of the step above)
+        if: always()
+        run: |
+          latest_epoch="$(git log -1 --format=%at "$(git tag --list 'image/v*' --sort=-v:refname | head -1)" 2>/dev/null || echo 0)"
+          now_epoch="$(date +%s)"
+          days=$(( (now_epoch - latest_epoch) / 86400 ))
+          threshold="${STALE_REBUILD_DAYS:-14}"
+          echo "days since last image tag: ${days} (threshold: ${threshold})"
+          if [[ "$days" -gt "$threshold" ]]; then
+            echo "::warning::no new image tag in ${days} days — check whether this workflow (or Renovate) is still running"
+          fi
+
+      - name: Tag and push
+        if: steps.next.outcome == 'success'
+        run: |
+          git config user.name "${{ gitea.actor }}"
+          git config user.email "${{ gitea.actor }}@noreply.git.morlana.online"
+          git tag "${{ steps.next.outputs.next_tag }}"
+          git push origin "${{ steps.next.outputs.next_tag }}"
+          echo "tagged ${{ steps.next.outputs.next_tag }} (rebuild of ${{ steps.next.outputs.latest_tag }}'s aptly version)"
+
+      - name: Report failure (opens an issue; the next successful run closes it)
+        if: always() && steps.next.outcome != 'success'
+        env:
+          GITEA_API: https://git.morlana.online/api/v1
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          curl -fsS -X POST "${GITEA_API}/repos/${{ gitea.repository }}/issues" \
+            -H "Authorization: token ${TOKEN}" -H "Content-Type: application/json" \
+            -d "{\"title\":\"rebuild.yaml failed on $(date -u +%F)\",\"body\":\"See the workflow run: ${{ gitea.server_url }}/${{ gitea.repository }}/actions\"}"

.gitea/workflows/release-chart.yaml

@@ -0,0 +1,99 @@
+name: Release chart
+# Triggered by `git tag chart/vX.Y.Z && git push --tags`, independently of
+# image releases — see docs/versioning.md. Never bumps the image: Chart.yaml's
+# committed appVersion (last set by release-image.yaml) is what gets packaged,
+# so a chart-only release always pins the last released image, never `latest`.
+#
+# Chart version is pure SemVer, deliberately WITHOUT the `+up<aptly>` build
+# metadata bookstack-chart uses: Helm rewrites `+` to `_` on OCI push (and
+# back on pull), which breaks listing in some third-party tooling (e.g.
+# Rancher). The aptly version lives in appVersion instead.
+on:
+  push:
+    tags:
+      - 'chart/v*'
+
+concurrency:
+  group: release-chart
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Parse chart version from tag
+        id: version
+        run: echo "version=${GITEA_REF_NAME#chart/v}" >> "$GITEA_OUTPUT"
+        env:
+          GITEA_REF_NAME: ${{ gitea.ref_name }}
+
+      - uses: azure/setup-helm@v4.3.0
+        with:
+          version: ${{ vars.HELM_VERSION || '3.16.4' }}
+
+      - name: Quality gate
+        run: |
+          set -e
+          helm lint charts/aptly
+          for f in charts/aptly/ci/*.yaml; do
+            helm template test charts/aptly -f "$f" > /dev/null
+          done
+
+      - name: Idempotency check — refuse to overwrite an existing chart version
+        run: |
+          if helm show chart "oci://git.morlana.online/f.weber/aptly" --version "${{ steps.version.outputs.version }}" >/dev/null 2>&1; then
+            echo "::error::chart version ${{ steps.version.outputs.version }} already exists in the registry. Bump the version and re-tag — this workflow never overwrites a published chart."
+            exit 1
+          fi
+
+      - name: Import GPG signing key
+        uses: crazy-max/ghaction-import-gpg@v6
+        with:
+          gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
+          passphrase: ${{ secrets.GPG_PASSPHRASE }}
+          trust_level: 5
+
+      - name: Build legacy secret keyring (helm package --sign wants gpg1-style secring.gpg)
+        run: |
+          mkdir -p /tmp/gpgring
+          gpg --batch --pinentry-mode loopback --passphrase "${{ secrets.GPG_PASSPHRASE }}" \
+            --export-secret-keys > /tmp/gpgring/secring.gpg
+          printf '%s' "${{ secrets.GPG_PASSPHRASE }}" > /tmp/gpgring/passphrase.txt
+          chmod 600 /tmp/gpgring/*
+
+      # secrets.GPG_KEY_ID/GPG_PRIVATE_KEY must be an RSA (or other classic,
+      # non-EdDSA) key — Helm's sign/verify uses the deprecated
+      # golang.org/x/crypto/openpgp library, which cannot read Ed25519 keys at
+      # all (fails with "private key not found"). See pubkeys/README.md.
+      - name: Package & sign
+        run: |
+          helm package charts/aptly \
+            --version "${{ steps.version.outputs.version }}" \
+            --dependency-update \
+            --sign --key "${{ secrets.GPG_KEY_ID }}" \
+            --keyring /tmp/gpgring/secring.gpg \
+            --passphrase-file /tmp/gpgring/passphrase.txt
+
+      - name: helm registry login & push
+        run: |
+          echo "${{ secrets.REGISTRY_TOKEN }}" | helm registry login git.morlana.online \
+            --username "${{ secrets.REGISTRY_USER }}" --password-stdin
+          helm push "aptly-${{ steps.version.outputs.version }}.tgz" oci://git.morlana.online/f.weber
+
+      - name: Create Gitea release with chart artifacts
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ gitea.ref_name }}
+          name: "aptly chart ${{ steps.version.outputs.version }}"
+          body: |
+            `helm pull oci://git.morlana.online/f.weber/aptly --version ${{ steps.version.outputs.version }}`
+          files: |
+            aptly-${{ steps.version.outputs.version }}.tgz
+            aptly-${{ steps.version.outputs.version }}.tgz.prov
+            pubkeys/chart-signing.asc
+
+      - name: Clean up key material
+        if: always()
+        run: rm -rf /tmp/gpgring

.gitea/workflows/release-image.yaml

@@ -0,0 +1,113 @@
+name: Release image
+# Triggered by `git tag image/vX.Y.Z-N && git push --tags`, independently of
+# chart releases (release-chart.yaml) — see docs/versioning.md. N is a
+# revision counter for rebuilds of the same aptly version (base-image CVE
+# patches — see rebuild.yaml), not a new aptly release.
+on:
+  push:
+    tags:
+      - 'image/v*'
+
+concurrency:
+  group: release-image
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Parse tag and assert it matches the Dockerfile
+        id: version
+        run: |
+          set -euo pipefail
+          tag="${GITEA_REF_NAME#image/v}"          # e.g. 1.6.3-1
+          aptly_version="${tag%-*}"                 # 1.6.3
+          revision="${tag##*-}"                     # 1
+          minor="${aptly_version%.*}"                # 1.6
+          from_dockerfile="$(grep -oP '(?<=^ARG APTLY_VERSION=)\S+' images/aptly-server/Dockerfile)"
+          if [[ "$from_dockerfile" != "$aptly_version" ]]; then
+            echo "::error::tag ${GITEA_REF_NAME} implies aptly ${aptly_version}, but images/aptly-server/Dockerfile has ARG APTLY_VERSION=${from_dockerfile}. Bump the Dockerfile and re-tag."
+            exit 1
+          fi
+          {
+            echo "full=${tag}"
+            echo "aptly_version=${aptly_version}"
+            echo "revision=${revision}"
+            echo "minor=${minor}"
+          } >> "$GITEA_OUTPUT"
+        env:
+          GITEA_REF_NAME: ${{ gitea.ref_name }}
+
+      - name: Verify registry secrets are set
+        run: |
+          test -n "${{ secrets.REGISTRY_USER }}" || { echo "::error::REGISTRY_USER is not set"; exit 1; }
+          test -n "${{ secrets.REGISTRY_TOKEN }}" || { echo "::error::REGISTRY_TOKEN is not set (needs write:package — GITEA_TOKEN cannot push packages on Gitea)"; exit 1; }
+
+      - uses: docker/login-action@v3
+        with:
+          registry: git.morlana.online
+          username: ${{ secrets.REGISTRY_USER }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+        with:
+          driver-opts: |
+            image=moby/buildkit:latest
+
+      - name: Build & push aptly-server
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: images/aptly-server/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          provenance: false
+          sbom: false
+          build-args: |
+            APTLY_VERSION=${{ steps.version.outputs.aptly_version }}
+            APTLY_REVISION=${{ steps.version.outputs.revision }}
+          tags: |
+            git.morlana.online/f.weber/aptly:${{ steps.version.outputs.full }}
+            git.morlana.online/f.weber/aptly:${{ steps.version.outputs.aptly_version }}
+            git.morlana.online/f.weber/aptly:${{ steps.version.outputs.minor }}
+            git.morlana.online/f.weber/aptly:latest
+
+      - name: Build & push aptly-deb-builder
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: images/aptly-deb-builder/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          provenance: false
+          sbom: false
+          tags: |
+            git.morlana.online/f.weber/aptly-deb-builder:${{ steps.version.outputs.full }}
+            git.morlana.online/f.weber/aptly-deb-builder:${{ steps.version.outputs.aptly_version }}
+            git.morlana.online/f.weber/aptly-deb-builder:latest
+
+      - name: Create Gitea release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ gitea.ref_name }}
+          name: "aptly image ${{ steps.version.outputs.full }}"
+          body: |
+            Images pushed:
+            - `git.morlana.online/f.weber/aptly:${{ steps.version.outputs.full }}` (+ `${{ steps.version.outputs.aptly_version }}`, `${{ steps.version.outputs.minor }}`, `latest`)
+            - `git.morlana.online/f.weber/aptly-deb-builder:${{ steps.version.outputs.full }}`
+
+      - name: Bump chart appVersion (pins the last released image; never main-latest)
+        run: |
+          set -euo pipefail
+          sed -i "s/^appVersion:.*/appVersion: \"${{ steps.version.outputs.full }}\"/" charts/aptly/Chart.yaml
+          git config user.name "${{ gitea.actor }}"
+          git config user.email "${{ gitea.actor }}@noreply.git.morlana.online"
+          git add charts/aptly/Chart.yaml
+          git diff --cached --quiet && exit 0
+          git commit -m "chore: bump chart appVersion to ${{ steps.version.outputs.full }} [skip ci]"
+          git push origin HEAD:main