Generate the documentation via templates

Rather than generating the documentation via Antora extension at website
build time, this generates the documentation using golang templates at
build time.

Reference: EC-513

.github/workflows/pre-merge-ci.yaml

@@ -20,11 +20,11 @@ name: pre-merge-ci
 on:
   pull_request:
     branches:
-    - main
+      - main
 
   push:
     branches:
-    - main
+      - main
 
   workflow_dispatch:
 
@@ -35,30 +35,39 @@ jobs:
   all-tests-and-checks:
     runs-on: ubuntu-latest
     steps:
-    - name: Harden Runner
-      uses: step-security/harden-runner@63c24ba6bd7ba022e95695ff85de572c04a18142 # v2.7.0
-      with:
-        egress-policy: audit
-        disable-telemetry: true
+      - name: Harden Runner
+        uses: step-security/harden-runner@63c24ba6bd7ba022e95695ff85de572c04a18142 # v2.7.0
+        with:
+          egress-policy: audit
+          disable-telemetry: true
 
-    - name: Checkout code
-      uses: actions/checkout@1d96c772d19495a3b5c517cd2bc0cb401ea0529f # v4.1.3
+      - name: Checkout code
+        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
 
-    - name: Setup Go environment
-      uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491 # v5.0.0
-      with:
-        go-version-file: go.mod
-        cache: true
+      - name: Setup Go environment
+        uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491 # v5.0.0
+        with:
+          go-version-file: go.mod
+          cache: true
 
-    - name: Run checks
-      run: make ci
+      - name: Run checks
+        run: make ci
 
-    # See https://issues.redhat.com/browse/HACBS-2391 to re-enable these checks
-    # - name: Validate added bundles
-    #   run: ./hack/validate-acceptable-bundles.sh
+      - name: Check for uncommitted changes
+        run: |
+          if ! git diff --exit-code -s; then
+            for f in $(git diff --exit-code --name-only); do
+              echo "::error file=$f,line=1,col=1,endColumn=1::File was modified in build"
+            done
+            exit 1
+          fi
 
-    - name: Upload test coverage report
-      uses: codecov/codecov-action@84508663e988701840491b86de86b666e8a86bed # v4.3.0
-      if: always()
-      env:
-        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+      # See https://issues.redhat.com/browse/HACBS-2391 to re-enable these checks
+      # - name: Validate added bundles
+      #   run: ./hack/validate-acceptable-bundles.sh
+
+      - name: Upload test coverage report
+        uses: codecov/codecov-action@84508663e988701840491b86de86b666e8a86bed # v4.3.0
+        if: always()
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

Makefile

@@ -160,29 +160,8 @@ annotations-opa:
 
 SHORT_SHA=$(shell git rev-parse --short HEAD)
 
-# (The git checkout is so we don't leave the preid diff in package.json)
-npm-publish: ## Publish the antora extension npm package. Requires a suitable NPM_TOKEN env var
-	cd antora/ec-policies-antora-extension && \
-	  npm version prerelease --preid $(SHORT_SHA) && \
-	  npm publish --access=public && \
-	  git checkout package.json
-
-EC_DOCS_DIR=../enterprise-contract.github.io
-EC_DOCS_REPO[email protected]:enterprise-contract/enterprise-contract.github.io.git
-$(EC_DOCS_DIR):
-	mkdir $(EC_DOCS_DIR) && cd $(EC_DOCS_DIR) && git clone $(EC_DOCS_REPO) .
-
-# See also the hack/local-build.sh script in the
-# enterprise-contract.github.io repo which does something similar
-CURRENT_BRANCH=$(shell git rev-parse --abbrev-ref HEAD)
-docs-preview: $(EC_DOCS_DIR) ## Build a preview of the documentation
-	cd antora/ec-policies-antora-extension && \
-	  npm ci
-	cd $(EC_DOCS_DIR)/antora && \
-	  yq e -i '.content.sources[] |= select(.url == "*ec-policies*").url |= "../../ec-policies"' antora-playbook.yml && \
-	  yq e -i '.content.sources[] |= select(.url == "*ec-policies*").branches |= "$(CURRENT_BRANCH)"' antora-playbook.yml && \
-	  yq e -i '.antora.extensions[] |= select(.require == "*ec-policies-antora-extension").require |= "../../ec-policies/antora/ec-policies-antora-extension"' antora-playbook.yml && \
-	  npm ci && npm run build
+generate-docs:
+	@cd docs && go run github.com/enterprise-contract/ec-policies/docs -adoc ../antora/docs/modules/ROOT -rego .. -rego "$$(go list -modfile ../go.mod -f '{{.Dir}}' github.com/enterprise-contract/ec-cli)/docs/policy/release"
 
 ##@ CI
 
@@ -205,7 +184,7 @@ lint-fix: ## Fix linting issues automagically
 	@go run github.com/google/addlicense -c '$(COPY)' -y '' -s $(LICENSE_IGNORE) .
 
 .PHONY: ci
-ci: quiet-test acceptance opa-check conventions-check fmt-check lint ## Runs all checks and tests
+ci: quiet-test acceptance opa-check conventions-check fmt-check lint generate-docs ## Runs all checks and tests
 
 #--------------------------------------------------------------------
 

antora/docs/modules/ROOT/pages/build_task_policy.adoc

@@ -0,0 +1,33 @@
+= Build Task Policy
+
+:numbered:
+
+These rules are applied to Tekton build task definitions.
+
+[#labels_package]
+== link:#labels_package[Tekton task build type label checks]
+
+Policies to verify that a Tekton build task definition has the required build type label.
+
+* Package name: `labels`
+* Package full path: `policy.build_task.labels`
+
+[#labels__build_type_label_set]
+=== link:#labels__build_type_label_set[Build task has build type label]
+
+Confirm the build task definition has the required build type label.
+
+* Rule type: [rule-type-indicator failure]#FAILURE#
+* FAILURE message: `The required build label '%s' is missing`
+* Code: `labels.build_type_label_set`
+* https://github.com/enterprise-contract/ec-policies/blob/{page-origin-refhash}/policy/build_task/labels.rego#L17[Source, window="_blank"]
+
+[#labels__build_task_has_label]
+=== link:#labels__build_task_has_label[Build task has label]
+
+Confirm that the build task definition includes at least one label.
+
+* Rule type: [rule-type-indicator failure]#FAILURE#
+* FAILURE message: `The task definition does not include any labels`
+* Code: `labels.build_task_has_label`
+* https://github.com/enterprise-contract/ec-policies/blob/{page-origin-refhash}/policy/build_task/labels.rego#L30[Source, window="_blank"]

antora/docs/modules/ROOT/pages/pipeline_policy.adoc

@@ -0,0 +1,149 @@
+= Pipeline Policy
+
+:numbered:
+
+These rules are applied to Tekton pipeline definitions.
+
+[#task_bundle_package]
+== link:#task_bundle_package[Pipeline definition Task bundle policies]
+
+To be able to reproduce and audit builds accurately it's important to know exactly what happens during the build. To do this Enterprise Contract requires that all tasks are defined in a set of known and trusted task bundles. This package includes rules to confirm that the tasks in a Pipeline definition are defined in task bundles, and that the task bundles are from the list of known and trusted bundles.
+
+* Package name: `task_bundle`
+* Package full path: `policy.pipeline.task_bundle`
+
+[#task_bundle__missing_required_data]
+=== link:#task_bundle__missing_required_data[Missing required data]
+
+Confirm the `trusted_tasks` rule data was provided, since it's required by the policy rules in this package.
+
+* Rule type: [rule-type-indicator failure]#FAILURE#
+* FAILURE message: `Missing required trusted_tasks data`
+* Code: `task_bundle.missing_required_data`
+* https://github.com/enterprise-contract/ec-policies/blob/{page-origin-refhash}/policy/pipeline/task_bundle.rego#L93[Source, window="_blank"]
+
+[#task_bundle__untrusted_task_bundle]
+=== link:#task_bundle__untrusted_task_bundle[Task bundle is not trusted]
+
+For each Task in the Pipeline definition, check if the Tekton Bundle used is a trusted task.
+
+* Rule type: [rule-type-indicator failure]#FAILURE#
+* FAILURE message: `Pipeline task '%s' uses an untrusted task bundle '%s'`
+* Code: `task_bundle.untrusted_task_bundle`
+* https://github.com/enterprise-contract/ec-policies/blob/{page-origin-refhash}/policy/pipeline/task_bundle.rego#L78[Source, window="_blank"]
+
+[#task_bundle__out_of_date_task_bundle]
+=== link:#task_bundle__out_of_date_task_bundle[Task bundle is out of date]
+
+For each Task in the Pipeline definition, check if the Tekton Bundle used is the most recent.
+
+* Rule type: [rule-type-indicator warning]#WARNING#
+* WARNING message: `Pipeline task '%s' uses an out of date task bundle '%s'`
+* Code: `task_bundle.out_of_date_task_bundle`
+* https://github.com/enterprise-contract/ec-policies/blob/{page-origin-refhash}/policy/pipeline/task_bundle.rego#L62[Source, window="_blank"]
+
+[#task_bundle__empty_task_bundle_reference]
+=== link:#task_bundle__empty_task_bundle_reference[Task bundle reference is empty]
+
+Check that a valid task bundle reference is being used.
+
+* Rule type: [rule-type-indicator failure]#FAILURE#
+* FAILURE message: `Pipeline task '%s' uses an empty bundle image reference`
+* Code: `task_bundle.empty_task_bundle_reference`
+* https://github.com/enterprise-contract/ec-policies/blob/{page-origin-refhash}/policy/pipeline/task_bundle.rego#L35[Source, window="_blank"]
+
+[#task_bundle__disallowed_task_reference]
+=== link:#task_bundle__disallowed_task_reference[Task bundle was not used or is not defined]
+
+Check for the existence of a task bundle. This rule will fail if the task is not called from a bundle.
+
+* Rule type: [rule-type-indicator failure]#FAILURE#
+* FAILURE message: `Pipeline task '%s' does not contain a bundle reference`
+* Code: `task_bundle.disallowed_task_reference`
+* https://github.com/enterprise-contract/ec-policies/blob/{page-origin-refhash}/policy/pipeline/task_bundle.rego#L21[Source, window="_blank"]
+
+[#task_bundle__unpinned_task_bundle]
+=== link:#task_bundle__unpinned_task_bundle[Unpinned task bundle reference]
+
+Check if the Tekton Bundle used for the Tasks in the Pipeline definition is pinned to a digest.
+
+* Rule type: [rule-type-indicator warning]#WARNING#
+* WARNING message: `Pipeline task '%s' uses an unpinned task bundle reference '%s'`
+* Code: `task_bundle.unpinned_task_bundle`
+* https://github.com/enterprise-contract/ec-policies/blob/{page-origin-refhash}/policy/pipeline/task_bundle.rego#L48[Source, window="_blank"]
+
+[#basic_package]
+== link:#basic_package[Pipeline definition sanity checks]
+
+Policies to confirm the Tekton Pipeline definition has the expected kind.
+
+* Package name: `basic`
+* Package full path: `policy.pipeline.basic`
+
+[#basic__expected_kind]
+=== link:#basic__expected_kind[Pipeline definition has expected kind]
+
+Confirm that the pipeline definition has the kind "Pipeline".
+
+* Rule type: [rule-type-indicator failure]#FAILURE#
+* FAILURE message: `Unexpected kind '%s' for pipeline definition`
+* Code: `basic.expected_kind`
+* https://github.com/enterprise-contract/ec-policies/blob/{page-origin-refhash}/policy/pipeline/basic.rego#L19[Source, window="_blank"]
+
+[#required_tasks_package]
+== link:#required_tasks_package[Required tasks]
+
+Konflux expects that certain Tekton tasks are executed during image builds. This package includes policy rules to confirm that the pipeline definition includes those required tasks.
+
+* Package name: `required_tasks`
+* Package full path: `policy.pipeline.required_tasks`
+
+[#required_tasks__missing_future_required_task]
+=== link:#required_tasks__missing_future_required_task[Missing future required task]
+
+Produce a warning when a task that will be required in the future is not currently included in the Pipeline definition.
+
+* Rule type: [rule-type-indicator warning]#WARNING#
+* WARNING message: `%s is missing and will be required on %s`
+* Code: `required_tasks.missing_future_required_task`
+* https://github.com/enterprise-contract/ec-policies/blob/{page-origin-refhash}/policy/pipeline/required_tasks.rego#L67[Source, window="_blank"]
+
+[#required_tasks__missing_required_task]
+=== link:#required_tasks__missing_required_task[Missing required task]
+
+Ensure that the set of required tasks is included in the Pipeline definition.
+
+* Rule type: [rule-type-indicator failure]#FAILURE#
+* FAILURE message: `%s is missing`
+* Code: `required_tasks.missing_required_task`
+* https://github.com/enterprise-contract/ec-policies/blob/{page-origin-refhash}/policy/pipeline/required_tasks.rego#L48[Source, window="_blank"]
+
+[#required_tasks__tasks_found]
+=== link:#required_tasks__tasks_found[Pipeline contains tasks]
+
+Confirm at least one task is present in the pipeline definition.
+
+* Rule type: [rule-type-indicator failure]#FAILURE#
+* FAILURE message: `No tasks found in pipeline`
+* Code: `required_tasks.tasks_found`
+* https://github.com/enterprise-contract/ec-policies/blob/{page-origin-refhash}/policy/pipeline/required_tasks.rego#L16[Source, window="_blank"]
+
+[#required_tasks__required_tasks_list_present]
+=== link:#required_tasks__required_tasks_list_present[Required task list is present in rule data]
+
+Confirm the `required-tasks` rule data was provided, since it's required by the policy rules in this package.
+
+* Rule type: [rule-type-indicator failure]#FAILURE#
+* FAILURE message: `The required tasks list is missing from the rule data`
+* Code: `required_tasks.required_tasks_list_present`
+* https://github.com/enterprise-contract/ec-policies/blob/{page-origin-refhash}/policy/pipeline/required_tasks.rego#L91[Source, window="_blank"]
+
+[#required_tasks__required_tasks_found]
+=== link:#required_tasks__required_tasks_found[Required tasks found in pipeline definition]
+
+Produce a warning if a list of current or future required tasks does not exist in the rule data.
+
+* Rule type: [rule-type-indicator warning]#WARNING#
+* WARNING message: `Required tasks do not exist for pipeline %q`
+* Code: `required_tasks.required_tasks_found`
+* https://github.com/enterprise-contract/ec-policies/blob/{page-origin-refhash}/policy/pipeline/required_tasks.rego#L29[Source, window="_blank"]