From 4953feba27c5efd31421a883dec7c5bd61ac40f5 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Thu, 30 Apr 2026 10:13:53 +0200 Subject: [PATCH 1/5] docs: move to diataxis structure Signed-off-by: Eike Waldt On-behalf-of: SAP --- docs/explanation/repo-infrastructure.md | 197 +++++++++++++++ docs/how-to/apt-repos.md | 304 ++++++++++++++++++++++++ 2 files changed, 501 insertions(+) create mode 100644 docs/explanation/repo-infrastructure.md create mode 100644 docs/how-to/apt-repos.md diff --git a/docs/explanation/repo-infrastructure.md b/docs/explanation/repo-infrastructure.md new file mode 100644 index 0000000..b94059f --- /dev/null +++ b/docs/explanation/repo-infrastructure.md @@ -0,0 +1,197 @@ +--- +title: Repository Infrastructure +description: Understand how Garden Linux assembles, distributes, and releases packages through its repository infrastructure +order: 103 +related_topics: + - /explanation/release-hierarchy.md + - /explanation/packaging.md + - /explanation/repo-infrastructure.md + - /explanation/os-releases.md + - /explanation/semver.md + - /how-to/packaging/backporting.md + - /how-to/releases/apt-repos.md + - /how-to/releases/os-releases.md + - /reference/releases/release-lifecycle +migration_status: "done" +migration_issue: "https://github.com/gardenlinux/gardenlinux/issues/4633" +migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter" +migration_approved: false +github_org: gardenlinux +github_repo: repo +github_source_path: docs/explanation/repo-infrastructure.md +github_target_path: docs/explanation/repo-infrastructure.md +--- + +# Repository Infrastructure + +This document provides a deep dive into the technical infrastructure that powers the Garden Linux repository system, including AWS setup, release processes and maintenance procedures. + +```mermaid +flowchart TD + repo[gardenlinux/repo] + snapshot[gardenlinux/repo-debian-snapshot] + pkg_build[gardenlinux/package-build] + pkg[gardenlinux/package-*] + ghcr_snapshot[ghcr.io/gardenlinux/repo-debian-snapshot] + s3[s3://gardenlinux-repo/gardenlinux] + s3_snapshot[s3://gardenlinux-repo/debian-snapshot] + deb[apt://deb.debian.org/debian] + + deb -- mirror --> snapshot + snapshot -- publish --> s3_snapshot + s3_snapshot -- ref --> ghcr_snapshot + snapshot -- publish --> ghcr_snapshot + + pkg_build -- use workflow / tooling --> pkg + ghcr_snapshot -- runs in --> pkg + + pkg -- get release artifacts --> repo + s3_snapshot -- get dependencies and imports --> repo + repo -- publish --> s3 +``` + +## Release Hierarchy + +Garden Linux uses a [three-tier release hierarchy](/explanation/release-hierarchy.md) to deliver a complete operating system. + +This document is about the second tier, the [Repository Infrastructure](/explanation/repo-infrastructure). + +## Debian Snapshots (`repo-debian-snapshot`) + +The [`repo-debian-snapshot`](https://github.com/gardenlinux/repo-debian-snapshot) repository provides the foundation for reproducible builds in Garden Linux by creating and maintaining timestamped snapshots of the Debian testing repository. + +### Purpose and Design Rationale + +Debian testing is a continuously evolving distribution where package versions change frequently. To ensure reproducible builds, Garden Linux needs to freeze dependency versions at specific points in time. While the official Debian snapshot service (snapshot.debian.org) archives the entire history of Debian, Garden Linux maintains its own selective snapshots optimized for the distribution's specific needs. + +The repo-debian-snapshot system was designed to address several requirements: + +- **Reproducibility**: Creating immutable snapshots of Debian testing at regular intervals ensures that builds performed today will produce identical results when repeated in the future +- **Timestamp-Based Versioning**: Each snapshot receives a codename based on its creation timestamp (e.g., `1743532800`), allowing precise identification of which Debian state was used for any given build +- **Long-Term Validity**: Snapshot repository metadata is signed with a 100-year validity period, preventing expiration issues that would break older builds. In contrast, the official Debian snapshot service uses keys with much shorter validity periods, which can cause builds to fail when accessing older snapshots +- **Performance**: Lightweight metadata-only snapshots are faster to create and require less storage than archiving full package files +- **Control**: Garden Linux can create snapshots at precisely the times needed for releases rather than relying on external snapshot schedules +- **AWS Integration**: Tight integration with AWS infrastructure enables seamless signing, storage, and distribution +- **Focused Scope**: Snapshots contain only what Garden Linux needs (testing, specific architectures) rather than the entire Debian archive history + +### What repo-debian-snapshot Does + +The repo-debian-snapshot repository contains the automation and tooling to create snapshots of the Debian testing repository. The snapshot process works as follows: + +1. **Mirror Creation**: The `mirror_apt_repo` script downloads package metadata (Packages and Sources files) from Debian testing for the architectures Garden Linux supports (amd64, arm64, and all). Rather than downloading all package files, it creates a minimal mirror containing only the metadata and a list of required packages. + +2. **Package Selection**: The system parses the downloaded metadata to identify which packages are needed. This creates a "mirrorlist" of URLs pointing to the actual `.deb` files on Debian mirrors, allowing on-demand retrieval without storing copies of every package. + +3. **Repository Generation**: The snapshot metadata is reorganized into a proper APT repository structure with: + - Package index files compressed with gzip + - SHA256 checksums for all files + - An InRelease file containing the repository metadata and checksums + - A validity period set to 100 years to prevent expiration issues + +4. **Cryptographic Signing**: The InRelease file is signed using GPG with keys stored in AWS KMS. The signing process uses the `gnupg-pkcs11-scd` tool to integrate GPG with KMS, ensuring private keys never leave AWS infrastructure. + +5. **Dual Publishing**: + - **S3 Repository**: The snapshot APT repository is published to `s3://gardenlinux-repo/debian-snapshot//` where it can be accessed by the `repo` assembly process + - **Container Images**: A Debian-based container image is built that includes the snapshot's APT configuration, published to GHCR (`ghcr.io/gardenlinux/repo-debian-snapshot`) + +### Usage in Garden Linux + +Debian snapshots serve two critical roles: + +1. **Build Environment**: Container images published to GHCR provide the build environment for `package-*` repositories. When a package is built, it runs inside a container based on a specific Debian snapshot, ensuring all build dependencies are at known versions. The container's `.container` file specifies which snapshot to use. + +2. **Dependency Source**: During Garden Linux release assembly, the `repo` workflow fetches dependencies from the appropriate Debian snapshot. This ensures that all packages in a Garden Linux release use consistent dependency versions. The system queries the snapshot's package indices to resolve dependencies and downloads required packages from the Debian mirror as needed. + +## AWS Infrastructure + +Garden Linux leverages AWS services to host and distribute its package repositories: + +### S3 Bucket Structure + +The `gardenlinux-repo` S3 bucket is organized as follows: + +- `/pool` - Contains all package files (.deb, .dsc, .tar.gz, etc.) used by both gardenlinux and debian-snapshot distributions +- `/gardenlinux` - Contains Garden Linux release distributions (dists/gardenlinux/\*) +- `/debian-snapshot` - Contains timestamp-indexed Debian testing snapshot distributions (dists/debian-snapshot/\*) + +### CloudFront Distribution + +- CloudFront ID: `E2RAO851VDQ2KX` +- Proxies the S3 bucket using a Lambda function (`repoPathRewrite`) +- Fixes an issue with AWS S3 HTTP endpoint handling `+` characters in filenames incorrectly +- Redirects all requests for `/*/pool` to `/pool` to allow sharing the pool directory between gardenlinux repo and debian-snapshot + +### IAM Roles and Policies + +- **Role**: `github-repo-oidc-role` + - Allows GitHub Actions workflows from repositories matching `gardenlinux/repo-*` to access AWS resources +- **Policy**: `github-repo-policy` + - Provides read/write access to the S3 bucket `gardenlinux-repo` + - Grants access to the Garden Linux repository signing key stored in KMS + +## Release Assembly Process + +The `repo` repository orchestrates the creation of Garden Linux APT repository releases through automated workflows. These APT repositories contain the packages that Garden Linux OS images consume during builds. + +:::info +This section describes **APT repository releases**. For information about **OS image releases** (which consume these APT repositories), see [Creating Major and Minor Releases](/how-to/releases/os-releases.md). +::: + +Garden Linux produces two types of APT repository releases: + +- **Nightly releases**: Automatically generated daily (e.g., `2150.0.0`) +- **Minor releases**: Manually created for specific updates (e.g., `2150.1.0`, `2150.2.0`) + +### Nightly Releases + +APT repositories for nightly releases are automatically generated by the `update.yml` GitHub Action that runs daily. These represent the latest state of Garden Linux with the newest custom-built packages and Debian snapshot dependencies. + +Each nightly repository release follows a structured process: + +1. **Release Tagging**: A new release is tagged with the [semantic versioning](/reference/glossary.html#semver) format `.0.0` (e.g., `2150.0.0`), where the version number is derived from the build date. Each tag includes a generated `package-releases` file that pins specific versions of custom-built packages to be included in this release. + +2. **Package Collection**: The system queries all `package-*` repositories to determine their build status: + - For packages that have successfully built, the system retrieves the built artifacts (`.deb` files, source packages, etc.) + - These artifacts are collected and prepared for inclusion in the APT repository + - Packages that failed to build or are not ready are excluded from the release, ensuring only working packages are distributed + +3. **Dependency Resolution**: For each package to be included in the release: + - The system examines the package's declared dependencies + - Required dependencies are fetched from the appropriate Debian snapshot repository + - Both the package itself and its dependencies are included in the final repository + - This ensures that all dependencies are available and versions are consistent across the entire release + +4. **Repository Assembly**: All collected packages and dependencies are organized into a proper APT repository structure with package indices, metadata, and checksums. + +5. **Cryptographic Signing**: The repository metadata is signed using the Garden Linux repository signing key stored in AWS KMS, ensuring authenticity and integrity. + +6. **Publication**: The final signed APT repository is published to the S3 bucket at `s3://gardenlinux-repo/gardenlinux`, making it available for Garden Linux OS builds and users to install or update systems. + +### Minor Releases + +APT repository minor releases are manually created to update specific packages in an existing release. They are typically used to backport critical fixes, security updates, or specific package updates to already-published versions. + +Key differences from nightly releases: + +- **Manual Creation**: Minor releases are created manually by checking out a nightly release tag, modifying the `package-releases` and `package-imports` files, and creating a new tag with an incremented minor number (e.g., `2150.1.0`, `2150.2.0`) +- **Selective Updates**: Only specific packages are updated, rather than collecting the latest state of all packages +- **Version Increment**: The minor number (third component of semantic versioning) is incremented while the base version remains the same +- **Targeted Purpose**: Used for backporting specific fixes or updates to stable versions that users are already running + +The assembly process for minor releases follows the same steps as nightly releases (dependency resolution, repository assembly, signing, publication), but operates on the manually curated `package-releases` and `package-imports` files rather than automatically generated ones. + +For detailed instructions on creating APT repository minor releases, see [Creating APT Repository Minor Releases](/how-to/releases/apt-repos.md). + +### Relationship to OS Releases + +APT repository releases are consumed by Garden Linux OS builds: + +1. An APT repository release is created (nightly or minor) +2. Garden Linux OS images are then built using packages from that APT repository +3. OS releases reference specific APT repository versions in their build configuration + +This separation allows package updates to be tested and staged in APT repositories before being incorporated into OS images. For information about creating OS releases, see [Creating Major and Minor Releases](/how-to/releases/os-releases.md). + +## Related Topics + + diff --git a/docs/how-to/apt-repos.md b/docs/how-to/apt-repos.md new file mode 100644 index 0000000..0688b9e --- /dev/null +++ b/docs/how-to/apt-repos.md @@ -0,0 +1,304 @@ +--- +title: Creating APT Repository Releases +description: Comprehensive guide to creating releases for Garden Linux APT repositories +order: 2 +related_topics: + - /explanation/release-hierarchy.md + - /explanation/packaging.md + - /explanation/repo-infrastructure.md + - /explanation/os-releases.md + - /explanation/semver.md + - /how-to/packaging/backporting.md + - /how-to/releases/apt-repos.md + - /how-to/releases/os-releases.md + - /reference/releases/release-lifecycle +migration_status: "done" +migration_issue: "https://github.com/gardenlinux/gardenlinux/issues/4705" +migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter" +migration_approved: false +github_org: gardenlinux +github_repo: repo +github_source_path: docs/how-to/releases/apt-repos.md +github_target_path: docs/how-to/releases/apt-repos.md +--- + +# Creating APT Repository Releases + +This guide explains how to create minor releases for Garden Linux APT repositories. APT repository releases contain the packages that Garden Linux OS images consume during builds. + +## Release Hierarchy + +Garden Linux uses a [three-tier release hierarchy](/explanation/release-hierarchy.md) to deliver a complete operating system. + +This document is about the second tier, the [Repository Infrastructure](/explanation/repo-infrastructure). + +## Understanding APT Repository Releases + +Please read the [APT Repository Infrastructure](/explanation/repo-infrastructure.md) to get familiar with the concepts for the Releases. + +## Prerequisites + +Before creating a minor release, ensure you have: + +- Write access to the `gardenlinux/repo` repository +- `git` and `gh` CLI tool installed and configured + +## Understanding package-releases and package-imports + +The `repo` repository uses two key files to define what goes into a release: + +### package-releases File + +The `package-releases` file lists the specific versions of custom-built packages from `package-*` repositories to include in the release. + +**Format**: Each line contains: + +``` + +``` + +**Example**: + +``` +containerd v1.7.13 +kernel 6.6.13 +openssh 9.6p1 +runc v1.1.12 +``` + +**How to determine versions**: + +1. Check the `package-*` repository for available release tags +2. Verify the package builds successfully in that version +3. Check dependencies and compatibility with other packages in the release + +**To update a package**: + +1. Find the package line in `package-releases` +2. Change the version tag to the desired release from the `package-*` repository +3. Verify that the new version is compatible with other packages + +### package-imports File + +The `package-imports` file specifies which packages should be imported directly from the Debian snapshot rather than being built from `package-*` repositories. + +**Format**: Each line contains a Debian package name: + +``` + +``` + +**Example**: + +``` +systemd +curl +glibc +``` + +**When to modify**: + +- **Add a package**: When switching from a custom build to using the Debian version +- **Remove a package**: When you've created a custom build and no longer want to import from Debian + +### Special Files + +- **`.container` file**: Specifies the `repo-debian-snapshot` container image used as the build environment. This is set automatically for major releases and typically should not be changed for minor releases to maintain reproducibility. + +## Creating a Minor Release + +Follow these steps to create an APT repository minor release: + +### Step 1: Prepare Your Environment + +```bash +# Clone the repo repository if you haven't already +git clone https://github.com/gardenlinux/repo.git +cd repo + +# Fetch all tags and branches +git fetch --tags +git fetch --all +``` + +### Step 2: Checkout the Base Release + +```bash +# Checkout the base release tag you want to minor +# For example, to create minor 2150.1.0 based on 2150.0.0: +git checkout 2150.0.0 + +# Create a release branch (use rel- naming convention) +git checkout -b rel-2150 + +# If the branch already exists, checkout and pull latest +# git checkout rel-2150 +# git pull origin rel-2150 +``` + +### Step 3: Modify Package Versions + +Edit the `package-releases` file to update package versions: + +```bash +# Open the file in your editor +vi package-releases + +# Example: Update containerd from v2.1.1 to v2.2.3 +# Change the line: +# gardenlinux/package-containerd 2.1.1-0gl0+bp2150 +# To: +# gardenlinux/package-containerd 2.2.3-0gl0+bp2150 +``` + +If you need to add or remove packages from Debian imports (e.g. because we are building it ourselves): + +```bash +# Edit package-imports file +vi package-imports + +# Add or remove Debian package names as needed +``` + +### Step 4: Verify Your Changes + +Review your changes carefully: + +```bash +# See what you've changed +git diff 2150.0.0 + +# Verify the package versions exist in their respective repositories +# For example, check that containerd v2.2.3 exists: +# https://github.com/gardenlinux/package-containerd/releases/tag/2.2.3-0gl0%2Bbp2150 +``` + +**Important checks**: + +- Verify all package versions in `package-releases` actually exist as releases in their respective repositories +- Ensure package versions are compatible with each other +- Check that dependency versions in Debian snapshot support your changes +- Consider impact on existing deployments + +### Step 5: Commit and Push + +```bash +# Commit your changes with a descriptive message +git add package-releases package-imports +git commit -m "Minor release 2150.1.0: Update containerd to v2.2.3-0gl0+bp2150 for CVE-2026-XXXXX" + +# Push the branch to GitHub +git push origin rel-2150 +``` + +### Step 6: Create the Release Tag + +```bash +# Create a tag for the new minor release +# Use semantic versioning: ..0 +git tag 2150.1.0 + +# Push the tag +git push origin 2150.1.0 +``` + +### Step 7: Monitor the Build + +Once you push the tag, the `update.yml` GitHub Action will automatically: + +1. Collect the specified package versions +2. Fetch dependencies from Debian snapshots +3. Assemble the APT repository +4. Sign it with the Garden Linux signing key +5. Publish to S3 + +Monitor the workflow: + +```bash +# Watch the workflow status +gh run watch +``` + +Or check the GitHub Actions page: https://github.com/gardenlinux/repo/actions + +## Verification and Testing + +After the minor release is published, verify it works correctly: + +### Verify APT Repository Structure + +Check that the repository was published to S3: + +```bash +# The repository should be available at: +# https://repo.gardenlinux.io/gardenlinux/dists/2150.1.0/ +``` + +### Test Package Installation + +In a test environment, configure the new repository and test package installation: + +```bash +# Add the repository (in a test Garden Linux system) +echo "deb https://repo.gardenlinux.io/gardenlinux 2150.1.0 main" > /etc/apt/sources.list.d/gardenlinux.list + +# Update package lists +apt update + +# Verify your updated packages are available +apt policy + +# Test installing/upgrading +apt install +``` + +### Verify Package Versions + +Confirm that the packages in the repository match your `package-releases` file: + +```bash +# Check package versions in the published repository +# This should show the versions you specified +apt-cache madison +``` + +## Troubleshooting + +### Build Failures + +If the GitHub Action fails: + +1. **Check the workflow logs**: Click on the failed workflow run in GitHub Actions +2. **Common issues**: + - **Package version doesn't exist**: Verify the tag exists in the `package-*` repository + - **Dependency conflicts**: Check if the new package version has dependency requirements that conflict with other packages + - **Build errors**: The package may have failed to build properly in the `package-*` repository + +### Package Not Found After Release + +If packages aren't appearing in the repository: + +1. Check that the workflow completed successfully +2. Verify the S3 bucket was updated (check timestamp) +3. Clear APT cache: `apt clean && apt update` +4. Check repository URL is correct in `/etc/apt/sources.list.d/` + +### Dependency Resolution Failures + +If you encounter dependency issues: + +1. Check which Debian snapshot is being used (from `.container` file) +2. Verify dependencies exist in that snapshot +3. Consider whether you need to import additional packages from Debian + +### Rolling Back a Minor Release + +If you need to rollback: + +1. Users can simply use the previous release: change APT sources to previous version tag +2. For OS builds, reference the previous APT repository version +3. If necessary, create a new minor release with reverted changes (do not delete tags) + +## Related Topics + + From 67a586243261a16a409305d43c9bf0a9fb07a6a2 Mon Sep 17 00:00:00 2001 From: Tiara Lena Hock Date: Wed, 20 May 2026 14:40:18 +0200 Subject: [PATCH 2/5] Docs: Rework Readme Signed-off-by: Tiara Lena Hock --- README.md | 155 +++++++++++++++--------------------------------------- 1 file changed, 42 insertions(+), 113 deletions(-) diff --git a/README.md b/README.md index 45bbb9d..b8e8486 100644 --- a/README.md +++ b/README.md @@ -1,115 +1,44 @@ # Gardenlinux Repo Infrastructure -```mermaid -flowchart TD - repo[gardenlinux/repo] - snapshot[gardenlinux/repo-debian-snapshot] - pkg_build[gardenlinux/package-build] - pkg[gardenlinux/package-*] - ghcr_snapshot[ghcr.io/gardenlinux/repo-debian-snapshot] - s3[s3://gardenlinux-repo/gardenlinux] - s3_snapshot[s3://gardenlinux-repo/debian-snapshot] - deb[apt://deb.debian.org/debian] - - deb -- mirror --> snapshot - snapshot -- publish --> s3_snapshot - s3_snapshot -- ref --> ghcr_snapshot - snapshot -- publish --> ghcr_snapshot - - pkg_build -- use workflow / tooling --> pkg - ghcr_snapshot -- runs in --> pkg - - pkg -- get release artifacts --> repo - s3_snapshot -- get dependencies and imports --> repo - repo -- publish --> s3 -``` - -## GitHub - -- `gardenlinux/repo` - - collect packages from `package-*` repos, fetch all dependencies from debian snapshot and publish into an APT repo distribution -- [`gardenlinux/repo-debian-snapshot`](https://github.com/gardenlinux/repo-debian-snapshot) - - regularly snapshot debian testing (needed for reproducible package and repo builds) -- [`gardenlinux/package-build`](https://github.com/gardenlinux/package-build) - - tooling used by `package-*` repos to build binary debian packages -- [`gardenlinux/package-*`](https://github.com/gardenlinux?q=package-&type=all&language=&sort=) - - repos for custom-built packages - -## AWS - -- bucket: `gardenlinux-repo` - - `/pool` for all package files - - `/gardenlinux` for gardenlinux release dists - - `/debian-snapshot` for time stamp indexed debian testing snapshot dists -- cloudfront: `E2RAO851VDQ2KX` - - proxies bucket `gardenlinux-repo` using lambda `repoPathRewrite` to fix problem with aws S3 http endpoint handling `+` in filenames incorrectly and redirects all requests for `/*/pool` to `/pool` => allowing to use a shared pool directory for gardenlinux repo and debian-snapshot -- role: `github-repo-oidc-role` - - allows all actions running in an environment 'aws' from repos matching 'gardenlinux/repo-*' to access -- policy: `github-repo-policy` - - gives read/write access to S3 bucket `gardenlinux-repo` - - gives access to gardenlinux repo signing key on KMS - -## Repo patch release workflow - -The `update.yml` GitHub action automatically creates daily releases of the form `.0`. -Each release corresponds to a tag of the same name in this repo. -These tags contain a generated file called `package-releases` that pins the custom build package versions to include in this release. - -To create a patch release, simply checkout this tag, adjust the `package-release` and `package-imports` files as needed, commit and tag this commit as `.X` - -``` -git fetch --tags -git checkout [-b] rel- -# modify package-releases and package-imports as needed -git commit -# push to release branch -git push origin rel- -# tag and push tag -git tag .1 -git push origin .1 -``` - -## Remove Garden Linux packages from the repo - -If, for whatever reason, we need to switch back to debian mirrored packages, a null release (with no content/assets) should be created. - -> [!IMPORTANT] -> DO NOT RENAME PACKAGE REPOS - -This is going to break future patch releases, if needed. Also, you should disable github actions for that repo, in order to prevent version updates from overwriting the null release. - -Create a branch to remove all files / actions, place a README to record the history for later reference and tag the repo with null as in below steps: - - - Create a branch called archive- with the last state of the repo. -``` - git checkout -b archive- -``` - - Disable GitHub Actions and other files -``` - git rm -r .github/workflows - git rm -r -``` - - Create a README.md to record what this package was and why was it needed -``` - git add README.md -``` - - Convert the branch to "null" branch -``` - git commit -a -m "null" - git push -u origin archive- -``` - - Create the PR for a review, once approved: - - Create a null tag for the repo -``` - git tag null - git push origin null -``` - - Create the Release (important), with a non-empty file -``` - echo null > ~/null - gh release create null ~/null --latest --notes null --title 'ignore package for repo import' -``` - - Archive the repo in GitHub -``` - Web browser > github.com/gardenlinux/package-NAME_repo > Settings > Danger Zone > Archive -``` +## Documentation + +Our [documentation hub](https://gardenlinux-docs.netlify.app/) contains detailed +documentation about the following topics in this repository: + +- [Repository Infrastructure](https://gardenlinux-docs.netlify.app/explanation/repo-infrastructure.html) +- [Creating APT Repository Releases](https://gardenlinux-docs.netlify.app/how-to/releases/apt-repos.html) + +# Community + +To stay up-to-date with recent news about Gardenlinux, subscribe to our mailing +list: + +https://lists.neonephos.org/g/gardenlinux-discussion + +For updates and statements regarding security issues, we have a security mailing +list for you: + +https://lists.neonephos.org/g/gardenlinux-security + +For embargoed security related topics, this list is for you: + +https://lists.neonephos.org/g/gardenlinux-security-embargo + +# Contributing + +We welcome your contributions to Gardenlinux or any supporting projects. + +To find our more, visit our +[Contributor Documentation](https://gardenlinux-docs.netlify.app/contributing). + +## Licensing + +Copyright 2025 SAP SE or an SAP affiliate company and GardenLinux contributors. +Please see our [LICENSE](LICENSE.md) for copyright and license information. +Detailed information including third-party components and their +licensing/copyright information is available +[via the REUSE tool](https://reuse.software). + +

+ Bundesministerium für Wirtschaft und Energie (BMWE)-EU funding logo +

From 9adfc48e8933c6f6a66f00bbfb28756259d04aa1 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Wed, 1 Jul 2026 17:12:46 +0200 Subject: [PATCH 3/5] feat: ci: add docs-check workflow Signed-off-by: Eike Waldt On-behalf-of: SAP --- .github/workflows/docs-check.yml | 74 ++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 .github/workflows/docs-check.yml diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml new file mode 100644 index 0000000..3ec4da5 --- /dev/null +++ b/.github/workflows/docs-check.yml @@ -0,0 +1,74 @@ +name: Documentation Quality Check + +on: + pull_request: + branches: [main, docs-ng] + types: [opened, synchronize, reopened, closed] + paths: + - 'docs/**' + push: + branches: [main, docs-ng] + paths: + - 'docs/**' + +jobs: + docs-checks: + # Skip checks on closed PRs (only need the notification) + if: github.event_name != 'pull_request' || github.event.action != 'closed' + uses: gardenlinux/docs-ng/.github/workflows/docs-checks.yml@main + with: + override-repo: ${{ github.event.repository.name }} + override-ref: ${{ github.head_ref || github.ref_name }} + override-commit: ${{ github.event.pull_request.head.sha || github.sha }} + + notify-docs-ng: + name: Notify docs-ng + needs: [docs-checks] + runs-on: ubuntu-24.04 + # Only notify for PR events (not push events which lack PR context) + # Run after checks pass for open PRs, OR immediately for merged PRs + if: | + always() && + github.event_name == 'pull_request' && + ( + (github.event.action == 'closed' && github.event.pull_request.merged == true) || + (github.event.action != 'closed' && needs.docs-checks.result == 'success') + ) + steps: + - name: Generate GitHub App token + id: app-token + uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0 + with: + app-id: ${{ secrets.DOCS_BOT_APP_ID }} + private-key: ${{ secrets.DOCS_BOT_PRIVATE_KEY }} + repositories: docs-ng + + - name: Send repository dispatch to docs-ng + uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1 + with: + github-token: ${{ steps.app-token.outputs.token }} + script: | + const isMergedPR = context.payload.action === 'closed' && + context.payload.pull_request.merged === true; + + // For merged PRs, use the base branch (the branch it was merged into) + // For open PRs, use the head branch (feature branch) + const ref = isMergedPR + ? context.payload.pull_request.base.ref + : context.payload.pull_request.head.ref; + + await github.rest.repos.createDispatchEvent({ + owner: 'gardenlinux', + repo: 'docs-ng', + event_type: 'docs-pr', + client_payload: { + repo: '${{ github.event.repository.name }}', + pr_number: `${context.payload.pull_request.number}`, + commit_sha: isMergedPR + ? context.payload.pull_request.merge_commit_sha + : context.payload.pull_request.head.sha, + ref: ref, + event: isMergedPR ? 'merged' : 'pr_success' + } + }); + core.info('Repository dispatch sent to docs-ng'); From 030acbd0d9c08da047e65f8becd28862aefecd17 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Tue, 7 Jul 2026 16:37:20 +0200 Subject: [PATCH 4/5] docs: use canonical class names for all mermaid diagrams Signed-off-by: Eike Waldt On-behalf-of: SAP Assisted-by: Kilo:claude-opus-4-7 Assisted-by: Kilo:claude-sonnet-4-6 --- docs/explanation/repo-infrastructure.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/explanation/repo-infrastructure.md b/docs/explanation/repo-infrastructure.md index b94059f..e5aa357 100644 --- a/docs/explanation/repo-infrastructure.md +++ b/docs/explanation/repo-infrastructure.md @@ -48,6 +48,10 @@ flowchart TD pkg -- get release artifacts --> repo s3_snapshot -- get dependencies and imports --> repo repo -- publish --> s3 + + class deb input + class snapshot,pkg_build,pkg,ghcr_snapshot,s3_snapshot,repo decision + class s3 output ``` ## Release Hierarchy From b38b34989ab4a80ed023a146173f6ef3e41b7c6e Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Tue, 14 Jul 2026 10:49:46 +0200 Subject: [PATCH 5/5] docs: remove "AI-generated phrasing" (#83) * docs: remove AI-generated phrasing Rules: HYPE-OPEN (2 occurrences), CANONICAL-LINT (2 occurrences) Signed-off-by: Eike Waldt On-behalf-of: SAP Assisted-by: Kilo:claude-opus-4-7 Assisted-by: Kilo:claude-sonnet-4-6 * docs(README.md): remove AI-generated phrasing Rules: CANONICAL-LINT (1 occurrence) Signed-off-by: Eike Waldt On-behalf-of: SAP Assisted-by: Kilo:claude-opus-4-7 Assisted-by: Kilo:claude-sonnet-4-6 * docs(docs/explanation/repo-infrastructure.md): remove AI-generated phrasing Rules: PROMO (1 occurrence), HYPE-OPEN (1 occurrence) Signed-off-by: Eike Waldt On-behalf-of: SAP Assisted-by: Kilo:claude-opus-4-7 Assisted-by: Kilo:claude-sonnet-4-6 --------- Signed-off-by: Eike Waldt --- README.md | 2 +- docs/explanation/repo-infrastructure.md | 6 +++--- docs/how-to/apt-repos.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index b8e8486..d8f77fc 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ To find our more, visit our ## Licensing Copyright 2025 SAP SE or an SAP affiliate company and GardenLinux contributors. -Please see our [LICENSE](LICENSE.md) for copyright and license information. +See our [LICENSE](LICENSE.md) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://reuse.software). diff --git a/docs/explanation/repo-infrastructure.md b/docs/explanation/repo-infrastructure.md index e5aa357..a0fa210 100644 --- a/docs/explanation/repo-infrastructure.md +++ b/docs/explanation/repo-infrastructure.md @@ -24,7 +24,7 @@ github_target_path: docs/explanation/repo-infrastructure.md # Repository Infrastructure -This document provides a deep dive into the technical infrastructure that powers the Garden Linux repository system, including AWS setup, release processes and maintenance procedures. +This document provides a describes the technical infrastructure that powers the Garden Linux repository system, including AWS setup, release processes and maintenance procedures. ```mermaid flowchart TD @@ -75,7 +75,7 @@ The repo-debian-snapshot system was designed to address several requirements: - **Long-Term Validity**: Snapshot repository metadata is signed with a 100-year validity period, preventing expiration issues that would break older builds. In contrast, the official Debian snapshot service uses keys with much shorter validity periods, which can cause builds to fail when accessing older snapshots - **Performance**: Lightweight metadata-only snapshots are faster to create and require less storage than archiving full package files - **Control**: Garden Linux can create snapshots at precisely the times needed for releases rather than relying on external snapshot schedules -- **AWS Integration**: Tight integration with AWS infrastructure enables seamless signing, storage, and distribution +- **AWS Integration**: Tight integration with AWS infrastructure enables automatic signing, storage, and distribution - **Focused Scope**: Snapshots contain only what Garden Linux needs (testing, specific architectures) rather than the entire Debian archive history ### What repo-debian-snapshot Does @@ -108,7 +108,7 @@ Debian snapshots serve two critical roles: ## AWS Infrastructure -Garden Linux leverages AWS services to host and distribute its package repositories: +Garden Linux uses AWS services to host and distribute its package repositories: ### S3 Bucket Structure diff --git a/docs/how-to/apt-repos.md b/docs/how-to/apt-repos.md index 0688b9e..060bb5b 100644 --- a/docs/how-to/apt-repos.md +++ b/docs/how-to/apt-repos.md @@ -1,6 +1,6 @@ --- title: Creating APT Repository Releases -description: Comprehensive guide to creating releases for Garden Linux APT repositories +description: Complete guide to creating releases for Garden Linux APT repositories order: 2 related_topics: - /explanation/release-hierarchy.md @@ -34,7 +34,7 @@ This document is about the second tier, the [Repository Infrastructure](/explana ## Understanding APT Repository Releases -Please read the [APT Repository Infrastructure](/explanation/repo-infrastructure.md) to get familiar with the concepts for the Releases. +Read the [APT Repository Infrastructure](/explanation/repo-infrastructure.md) to get familiar with the concepts for the Releases. ## Prerequisites