Update README (#3)

typisttech · Sep 27, 2024 · 34235e2 · 34235e2
1 parent 1ed2525
commit 34235e2
Showing 1 changed file with 221 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -26,11 +26,230 @@
 
 ## Usage
 
-TODO.
+### Inputs
+
+```yaml
+- uses: typisttech/upload-goreleaser-sboms-action@v0
+  with:
+    # Name of the artifact to upload.
+    # Required. Default is 'sboms'
+    name:
+    # Path to the dist folder which containing artifacts.json
+    # Required. Default is 'dist'
+    dist:
+    # The SBOM suffix.
+    #
+    # This action expects the SBOM is named after its subject with a suffix under the same directory.
+    # 
+    # See [Known Issues](https://github.com/typisttech/upload-goreleaser-sboms-action?tab=readme-ov-file#known-issues)
+    # 
+    # Required. Default is '.sbom.json'
+    sbom-suffix:
+
+    # Duration after which artifact will expire in days. 0 means using default retention.
+    # Minimum 1 day.
+    # Maximum 90 days unless changed from the repository settings page.
+    # Required. Defaults to repository settings.
+    retention-days:
+
+    # The level of compression for Zlib to be applied to the artifact archive.
+    # The value can range from 0 to 9.
+    # For large files that are not easily compressed, a value of 0 is recommended for significantly faster uploads.
+    # Required. Default is '6'
+    compression-level:
+```
+
+### Outputs
+
+| Name | Description | Example |
+| - | - | - |
+| `attestations` | Array of **subject** and **sbom** paris. | `[{"subject":"dist/foo","sbom":"dist/foo.sbom.json"},{"subject":"dist/bar","sbom":"dist/bar.sbom.json"}]` |
+| `artifact-id` | GitHub ID of an Artifact. This ID can be used as input to other APIs to download, delete or get more information about an artifact: [https://docs.github.com/en/rest/actions/artifacts](https://docs.github.com/en/rest/actions/artifacts) | `1234` |
+
+## Examples
+
+### Basic
+
+```yaml
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      sbom-artifact-id: ${{ steps.upload-sbom.outputs.artifact-id }}
+      sbom-attestations: ${{ steps.upload-sbom.outputs.attestations }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'
+      - uses: anchore/sbom-action/download-syft@v0
+      - uses: goreleaser/goreleaser-action@v6
+        with:
+          version: '~> v2'
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - uses: typisttech/upload-goreleaser-sboms-action@v0
+        id: upload-sbom
+
+  attest-sbom:
+    needs: [release]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      attestations: write
+    strategy:
+      matrix:
+        attestation: ${{ fromJSON(needs.release.outputs.sbom-attestations) }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: 'sboms'
+      - uses: actions/attest-sbom@v1
+        with:
+          subject-path: ${{ matrix.attestation.subject }}
+          sbom-path: ${{ matrix.attestation.sbom }}
+```
+
+### Attest Build Provenance and SBOMs & Verify & Cleanup
+
+```yaml
+on:
+  push:
+    tags:
+      - '*'
+
+permissions: {}
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      build-provenance-artifact-id: ${{ steps.upload-build-provenance.outputs.artifact-id }}
+      sbom-artifact-id: ${{ steps.upload-sbom.outputs.artifact-id }}
+      sbom-attestations: ${{ steps.upload-sbom.outputs.attestations }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'
+      - uses: anchore/sbom-action/download-syft@v0
+      - uses: goreleaser/goreleaser-action@v6
+        with:
+          version: '~> v2'
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/upload-artifact@v4
+        id: upload-build-provenance
+        with:
+          name: build-provenance
+          path: |
+            dist/my-cmd_*/my-cmd
+            dist/my-cmd_*.tar.gz
+            dist/**/*.sbom.json
+      - uses: typisttech/upload-goreleaser-sboms-action@v0
+        id: upload-sbom
+        with:
+          name: sbom-artifact
+
+  attest-build-provenance:
+    needs: [release]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          name: build-provenance
+      - uses: actions/attest-build-provenance@v1
+        with:
+          subject-path: |
+            dist/my-cmd_*/my-cmd
+            dist/my-cmd_*.tar.gz
+            dist/**/*.sbom.json
+
+  attest-sbom:
+    needs: [release]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      attestations: write
+    strategy:
+      matrix:
+        attestation: ${{ fromJSON(needs.release.outputs.sbom-attestations) }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: sbom-artifact
+      - uses: actions/attest-sbom@v1
+        with:
+          subject-path: ${{ matrix.attestation.subject }}
+          sbom-path: ${{ matrix.attestation.sbom }}
+
+  verify:
+    needs: [release, attest-build-provenance, attest-sbom]
+    runs-on: ubuntu-latest
+    steps:
+      - run: gh release download --clobber --dir artifacts --repo $REPO $TAG
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          TAG: ${{ github.ref_name }}
+      - run: tree artifacts
+      - run: ls | xargs -I {} gh attestation verify --repo $REPO {}
+        working-directory: artifacts
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+
+  cleanup:
+    needs: [release, verify]
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+    steps:
+      - run: >
+          gh api --method DELETE -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" /repos/$REPO/actions/artifacts/$ARTIFACT_ID
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          ARTIFACT_ID: ${{ needs.release.outputs.build-provenance-artifact-id }}
+      - run: >
+          gh api --method DELETE -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" /repos/$REPO/actions/artifacts/$ARTIFACT_ID
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          ARTIFACT_ID: ${{ needs.release.outputs.sbom-artifact-id }}
+```
 
 ## Known Issues
 
-TODO.
+### SBOM Suffix
+
+This action expects the SBOM is named after its subject with a suffix under the same directory.
+
+For example:
+
+```console
+$ tree dist
+dist
+├── artifacts.json
+├── my-cmd_1.2.3_darwin_amd64.tar.gz
+├── my-cmd_1.2.3_darwin_amd64.tar.gz.sbom.json
+├── my-cmd_1.2.3_linux_arm64.tar.gz
+└── my-cmd_1.2.3_linux_arm64.tar.gz.sbom.json
+```
 
 ## Credits