chainguard-dev · xnox · Aug 26, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -1,5 +1,2 @@
-docs/*.md linguist-generated=true
-docs/initial-setup.md linguist-generated=false
-docs/apko-cache.md linguist-generated=false
 MODULE.bazel.lock linguist-generated=true
 **/apko.lock.json linguist-generated=true
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -33,7 +33,7 @@
        with:
          egress-policy: audit
      - id: linux
        run: echo "os=ubuntu-latest" >> $GITHUB_OUTPUT
    outputs:
      # Will look like ["ubuntu-latest"]
      os: ${{ toJSON(steps.*.outputs.os) }}
@@ -48,13 +48,13 @@
          egress-policy: audit
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - id: bazel_91
        run: echo "bazelversion=9.1.0" >> $GITHUB_OUTPUT
      - id: bazel_86
        run: echo "bazelversion=8.6.0" >> $GITHUB_OUTPUT
      - id: bazel_83
        run: echo "bazelversion=8.3.0" >> $GITHUB_OUTPUT
      - id: bazel_76
        run: echo "bazelversion=7.6.1" >> $GITHUB_OUTPUT
    outputs:
      # Will look like ["<version from .bazelversion>", "x.y.z"]
      bazelversions: ${{ toJSON(steps.*.outputs.bazelversion) }}
@@ -104,15 +104,8 @@
 
       - name: Test
         working-directory: ${{ matrix.folder }}
-        if: ${{ matrix.bazelversion >= '9.' || matrix.folder != '.' }}
         run: bazel test //...
 
-      # Stardoc has output changes between versions
-      - name: Test no doc 8 and lower
-        working-directory: ${{ matrix.folder }}
-        if: ${{ matrix.bazelversion <= '8.' && matrix.folder == '.' }}
-        run: bazel query 'tests(//...) except docs/...' | xargs bazel test
-
   # Single summary gate that aggregates the dynamic test matrix. Branch
   # protection only needs to require this one context, so the Bazel version
   # matrix above can change without an infra change to the required checks.

diff --git a/MODULE.bazel b/MODULE.bazel
@@ -14,7 +14,6 @@ bazel_dep(name = "rules_oci", version = "2.3.0", dev_dependency = True)
 bazel_dep(name = "gazelle", version = "0.52.2", dev_dependency = True, repo_name = "bazel_gazelle")
 bazel_dep(name = "bazel_skylib_gazelle_plugin", version = "1.9.2", dev_dependency = True)
 bazel_dep(name = "buildifier_prebuilt", version = "8.5.1.3", dev_dependency = True)
-bazel_dep(name = "stardoc", version = "0.8.1", dev_dependency = True, repo_name = "io_bazel_stardoc")
 
 toolchain = use_extension("//apko:extensions.bzl", "apko")
 toolchain.toolchain(apko_version = "v1.2.40")

diff --git a/README.md b/README.md
@@ -43,7 +43,66 @@ See the examples folder in this repository, which relies on base layers declared
 
 Also see the `e2e` folder in this repository, where we declare our end-to-end test.
 
+## Fetching and Caching Contents
+
+To ensure efficient operation, the `apko_image` rule must maintain a cache of remote contents that it fetches from repositories. While outside of Bazel, `apko` manages its own cache, under Bazel, the cache must be maintained by Bazel to ensure correctness and speed. Therefore, Bazel needs to know what needs to be fetched and from where to cache these HTTP requests and provide them to `apko` as required.
+
+The `apko.lock.json` file contains all the necessary information about how to perform the HTTP fetches required by `apko` to build the container image.
+
+### Generating the Lock File
+
+> **Note:** Documentation for lockfile generation will be added once the `apko lock` command is available.
+
+### Using `translate_lock`
+
+Having just the `apko/lock.json` file alone is insufficient; all the information needs to be converted into `apk_<content_type>` repository calls to make them accessible to Bazel. The `translate_lock` tool accomplishes this by taking the `apko.lock.json` file and dynamically generating the required Bazel repositories.
+
+`translate_lock` will create a new bazel repository named after itself. this repository will also have a target named contents, which you can pass to apko_image:
+
+```starlark
+apko_image(
+    name = "lock",
+    config = "apko.yaml",
+    # name of the repository is the same translate_lock!
+    contents = "@examples_lock//:contents",
+    tag = "lock:latest",
+)
+```
+
+#### Usage with `bzlmod`
+
+```starlark
+apk = use_extension("@rules_apko//apko:extensions.bzl", "apko")
+
+apk.translate_lock(
+    name = "examples_lock",
+    lock = "//path/to/lock:apko.lock.json",
+)
+use_repo(apk, "examples_lock")
+```
+
+#### Usage with Workspace
+
+```starlark
+load("@rules_apko//apko:translate_lock.bzl", "translate_apko_lock")
+
+translate_apko_lock(
+    name = "example_lock",
+    lock = "//path/to/lock:apko.lock.json",
+)
+
+load("@example_lock//:repositories.bzl", "apko_repositories")
+
+apko_repositories()
+```
+
 ## Public API
 
-- [translate_lock](./docs/translate_lock.md) Repository rules for translating `apko.lock.json`
-- [rules](./docs/rules.md) Build OCI images from APK packages directly without `Dockerfile`
+The API reference is generated from the sources and rendered on the Bazel
+Central Registry: <https://registry.bazel.build/modules/rules_apko/latest/docs>
+
+- `translate_lock` Repository rules for translating `apko.lock.json`
+- `apko_image` Build OCI images from APK packages directly without `Dockerfile`
+
+See [Fetching and Caching Contents](#fetching-and-caching-contents) for how
+contents are fetched and cached.
diff --git a/apko/private/apko_image.bzl b/apko/private/apko_image.bzl
@@ -6,7 +6,7 @@ load("//apko/private:apko_config.bzl", "copy_to_workdir", "prepare_apko_config_i
 load("//apko/private:apko_run.bzl", "apko_run")
 
 _ATTRS = {
-    "contents": attr.label(doc = "Label to the contents repository generated by translate_lock. See [apko-cache](./apko-cache.md) documentation.", mandatory = True, providers = [OutputGroupInfo]),
+    "contents": attr.label(doc = "Label to the contents repository generated by translate_lock. See the [apko-cache](https://github.com/chainguard-dev/rules_apko/blob/main/README.md#fetching-and-caching-contents) documentation.", mandatory = True, providers = [OutputGroupInfo]),
     "config": attr.label(doc = "Label to the `apko.yaml` file.", allow_single_file = True, mandatory = True),
     "output": attr.string(default = "oci", values = ["oci", "docker"]),
     "architecture": attr.string(doc = "the CPU architecture which this image should be built to run on. See https://github.com/chainguard-dev/apko/blob/main/docs/apko_file.md#archs-top-level-element"),
@@ -152,7 +152,7 @@ def apko_image(
     ```
 
     The label `@example_lock//:contents` is generated by the `translate_lock` extension, which consumes an 'apko.lock.json' file.
-    For more details, refer to the [documentation](./docs/apko-cache.md).
+    For more details, refer to the [apko-cache](https://github.com/chainguard-dev/rules_apko/blob/main/README.md#fetching-and-caching-contents) documentation.
 
     An example demonstrating usage with [rules_oci](https://github.com/bazel-contrib/rules_oci)
 
@@ -174,7 +174,7 @@ def apko_image(
 
     Args:
      name:         of the target for the generated image.
-     contents:     Label to the contents repository generated by translate_lock. See [apko-cache](./apko-cache.md) documentation.
+     contents:     Label to the contents repository generated by translate_lock. See the [apko-cache](https://github.com/chainguard-dev/rules_apko/blob/main/README.md#fetching-and-caching-contents) documentation.
      config:       Label to the `apko.yaml` file.  For more advanced use-cases (multi-file configuration), use target providing `ApkoConfigInfo`
         (e.g. output of `apko_config` rule).
      output:       "oci" of  "docker",

diff --git a/apko/translate_lock.bzl b/apko/translate_lock.bzl
@@ -5,7 +5,7 @@ load("//apko/private:util.bzl", "util")
 
 _DOC = """Repository rule to generate starlark code from an `apko.lock.json` file.
 
-See [apko-cache.md](./apko-cache.md) documentation.
+See the [apko-cache](https://github.com/chainguard-dev/rules_apko/blob/main/README.md#fetching-and-caching-contents) documentation.
 """
 
 BUILD_TMPL = """\

diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
diff --git a/docs/apko-cache.md b/docs/apko-cache.md
diff --git a/docs/rules.md b/docs/rules.md
diff --git a/docs/translate_lock.md b/docs/translate_lock.md