Document jreleaser/jreleaser#1651

jreleaser · Jun 5, 2024 · 762d43f · 762d43f
1 parent 0d52653
commit 762d43f
Show file tree

Hide file tree

Showing 3 changed files with 291 additions and 0 deletions.
diff --git a/docs/modules/ROOT/pages/integrations.adoc b/docs/modules/ROOT/pages/integrations.adoc
@@ -42,6 +42,7 @@ Assembled artifacts, distribution artifacts, and files may be cataloged:
  * xref:reference:catalog/sbom/syft.adoc[]
 
 .Provenance
+ * xref:reference:catalog/github.adoc[]
  * xref:reference:catalog/slsa.adoc[]
 
 .Tracking

diff --git a/docs/modules/reference/nav.adoc b/docs/modules/reference/nav.adoc
@@ -28,6 +28,7 @@
 *** xref:assemble/jpackage.adoc[]
 *** xref:assemble/native-image.adoc[]
 ** xref:catalog/index.adoc[]
+*** xref:catalog/github.adoc[]
 *** xref:catalog/sbom/index.adoc[]
 **** xref:catalog/sbom/cyclonedx.adoc[]
 **** xref:catalog/sbom/syft.adoc[]

diff --git a/docs/modules/reference/pages/catalog/github.adoc b/docs/modules/reference/pages/catalog/github.adoc
@@ -0,0 +1,289 @@
+= Github Attestation
+:cataloger_sys_key: github
+:cataloger_env_key: GITHUB
+
+Generates a list of artifacts that may be supplied as input to the link:https://github.com/actions/attest-build-provenance[actions/attest-build-provenance]
+GitHub Action. The list will be saved in a file named after the chosen `attestationName`. The contents of this file may
+be used as an input, for example
+
+*my-release-workflow.yml*
+```yaml
+      - name: Release
+        uses: jreleaser/release-action@v2
+        with:
+          arguments: release
+        env:
+          JRELEASER_PROJECT_VERSION: <my-project-version>
+
+      - run: echo "ARTIFACTS=$(cat out/jreleaser/catalogs/github/<my-chosen-attestation-name>)" >> $GITHUB_OUTPUT
+
+      - name: Attestations
+        uses: actions/attest-build-provenance@v1
+        with:
+          subject-path: |
+            ${{ ARTIFACTS }}
+```
+
+== Configuration
+
+include::partial$legend.adoc[]
+
+[tabs]
+====
+YAML::
++
+--
+[source,yaml]
+[subs="+macros,attributes"]
+----
+catalog:
+  # icon:dot-circle[]
+  github:
+
+    # Enable or disable this cataloger.
+    # Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
+    # Defaults to `NEVER`.
+    # icon:dot-circle[] icon:eye-slash[]
+    active: ALWAYS
+
+    # Name of the attestation file.
+    # Defaults to `{{projectName}}-{{projectEffectiveVersion}}`.
+    # icon:dot-circle[] icon:file-alt[]
+    attestationName: 'app-all-{{projectVersion}}'
+
+    # Check distribution artifacts.
+    # Defaults to `true`.
+    # icon:dot-circle[]
+    artifacts: true
+
+    # Check files.
+    # Defaults to `true`.
+    # icon:dot-circle[]
+    files: true
+
+    # Check deployable artifacts.
+    # Defaults to `true`.
+    # icon:dot-circle[]
+    deployables: true
+
+    # Additional properties used when evaluating templates.
+    # icon:dot-circle[] icon:file-alt[]
+    extraProperties:
+      # Key will be capitalized and prefixed with `github`, i.e, `githubFoo`.
+      foo: bar
+----
+--
+TOML::
++
+--
+[source,toml]
+[subs="+macros,attributes"]
+----
+# icon:dot-circle[]
+[catalog.github]
+
+  # Enable or disable this cataloger.
+  # Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
+  # Defaults to `NEVER`.
+  # icon:dot-circle[] icon:eye-slash[]
+  active = "ALWAYS"
+
+   # Name of the attestation file.
+   # Defaults to `{{projectName}}-{{projectEffectiveVersion}}`.
+   # icon:dot-circle[] icon:file-alt[]
+   attestationName = "app-all-{{projectVersion}}"
+
+   # Check distribution artifacts.
+   # Defaults to `true`.
+   # icon:dot-circle[]
+   artifacts = true
+
+   # Check files.
+   # Defaults to `true`.
+   # icon:dot-circle[]
+   files = true
+
+   # Check deployable artifacts.
+   # Defaults to `true`.
+   # icon:dot-circle[]
+   deployables = true
+
+  # Additional properties used when evaluating templates.
+  # icon:dot-circle[] icon:file-alt[]
+  extraProperties.foo = "bar"
+  # Key will be capitalized and prefixed with `github`, i.e, `githubFoo`.
+----
+--
+JSON::
++
+--
+[source,json]
+[subs="+macros,attributes"]
+----
+{
+  "catalog": {
+    // icon:dot-circle[]
+    "github": {
+
+      // Enable or disable this cataloger.
+      // Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
+      // Defaults to `NEVER`.
+      // icon:dot-circle[] icon:eye-slash[]
+      "active": "ALWAYS",
+
+      // Name of the attestation file.
+      // Defaults to `{{projectName}}-{{projectEffectiveVersion}}`.
+      // icon:dot-circle[] icon:file-alt[]
+      "attestationName": "app-all-{{projectVersion}}",
+
+      // Check distribution artifacts.
+      // Defaults to `true`.
+      // icon:dot-circle[]
+      "artifacts": true,
+
+      // Check files.
+      // Defaults to `true`.
+      // icon:dot-circle[]
+      "files": true,
+
+      // Check deployable artifacts.
+      // Defaults to `true`.
+      // icon:dot-circle[]
+      "deployables": true,
+
+      // Additional properties used when evaluating templates.
+      // icon:dot-circle[] icon:file-alt[]
+      "extraProperties": {
+        // Key will be capitalized and prefixed with `github`, i.e, `githubFoo`.
+        "foo": "bar"
+      }
+    }
+  }
+}
+----
+--
+Maven::
++
+--
+[source,xml]
+[subs="+macros,attributes,verbatim"]
+----
+<jreleaser>
+  <!--
+    icon:dot-circle[]
+  -->
+  <catalog>
+    <!--
+      icon:dot-circle[]
+    -->
+    <github>
+
+      <!--
+        Enable or disable this cataloger.
+        Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
+        Defaults to `NEVER`.
+        icon:dot-circle[] icon:eye-slash[]
+      -->
+      <active>ALWAYS</active>
+
+      <!--
+        Name of the attestation file.
+        Defaults to `{{projectName}}-{{projectEffectiveVersion}}`.
+        icon:dot-circle[] icon:file-alt[]
+      -->
+      <attestationName>app-all-{{projectVersion}}</attestationName>
+
+      <!--
+        Check distribution artifacts.
+        Defaults to `true`.
+        icon:dot-circle[]
+      -->
+      <artifacts>true</artifacts>
+
+      <!--
+        Check files.
+        Defaults to `true`.
+        icon:dot-circle[]
+      -->
+      <files>true</files>
+
+      <!--
+        Check deployable artifacts.
+        Defaults to `true`.
+        icon:dot-circle[]
+      -->
+      <deployables>true</deployables>
+
+      <!--
+        Additional properties used when evaluating templates.
+        icon:dot-circle[] icon:file-alt[]
+      -->
+      <extraProperties>
+        <!--
+          Key will be capitalized and prefixed with `github`, i.e, `githubFoo`.
+        -->
+        <foo>bar</foo>
+      </extraProperties>
+    </github>
+  </catalog>
+</jreleaser>
+----
+--
+Gradle::
++
+--
+[source,groovy]
+[subs="+macros,attributes"]
+----
+jreleaser {
+  catalog {
+    // icon:dot-circle[]
+    github {
+
+      // Enable or disable this cataloger.
+      // Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
+      // Defaults to `NEVER`.
+      // icon:dot-circle[] icon:eye-slash[]
+      active = 'ALWAYS'
+
+      // Name of the attestation file.
+      // Defaults to `{{projectName}}-{{projectEffectiveVersion}}`.
+      // icon:dot-circle[] icon:file-alt[]
+      attestationName = 'app-all-{{projectVersion}}'
+
+      // Check distribution artifacts.
+      // Defaults to `true`.
+      // icon:dot-circle[]
+      artifacts = true
+
+      // Check files.
+      // Defaults to `true`.
+      // icon:dot-circle[]
+      files = true
+
+      // Check deployable artifacts.
+      // Defaults to `true`.
+      // icon:dot-circle[]
+      deployables = true
+
+      // Additional properties used when evaluating templates.
+      // Key will be capitalized and prefixed with `github`, i.e, `githubFoo`.
+      // icon:dot-circle[] icon:file-alt[]
+      extraProperties.put('foo', 'bar')
+    }
+  }
+}
+----
+--
+====
+
+include::partial$envvars-header.adoc[]
+
+[%header, cols="<1,<1", width="100%"]
+|===
+| System Property                               | Environment Variable
+2+| *active*
+| jreleaser.catalog.{cataloger_sys_key}.active | JRELEASER_CATALOG_{cataloger_env_key}_ACTIVE
+2+| *attestationName*
+| jreleaser.catalog.{cataloger_sys_key}.attestation.name | JRELEASER_CATALOG_{cataloger_env_key}_ATTESTATION_NAME
+|===