Walrus Sites Provenance

Overview

This guide explains how to use the walrus-sites-provenance GitHub Action to deploy static websites to Walrus Sites with full SLSA-backed provenance.

Each deployment:

• Generates a signed .intoto.jsonl provenance file
• Links it to your GitHub commit, workflow, and identity (via OIDC)
• Uploads it alongside your Walrus-hosted static site
• Enables verification via notary.wal.app

This ensures your frontend is verifiably built, tamper-resistant, and on-chain.

Features

• ✅ SLSA Level 3-compliant provenance
• 🔐 GitHub OIDC-based identity linking
• 🧾 Sigstore signing (no manual GPG keys)
• 🔁 Remote signing with GitSigner (optional)
• 🌐 Verification via notary.wal.app

Quick Start

Add the GitHub Action to your workflow:

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Walrus Sites
        uses: zktx-io/walrus-sites-provenance@v0.4.10
        env:
          ED25519_PRIVATE_KEY: ${{ secrets.ED25519_PRIVATE_KEY }}
          # or for GitSigner:
          GIT_SIGNER_PIN: ${{ secrets.GIT_SIGNER_PIN }}

⚠️ Your project must include a site.config.json at the root.

Configuration: site.config.json

This file defines how your site will be deployed:

{
  "network": "testnet",
  "owner": "0x1234567890abcdef1234567890abcdef12345678",
  "site_name": "my-walrus-site",
  "metadata": {
    "link": "https://myproject.xyz",
    "image_url": "https://myproject.xyz/preview.png",
    "name": "My Project",
    "description": "A decentralized web app deployed on Walrus.",
    "project_url": "https://github.com/my-org/my-walrus-site",
    "creator": "my-org"
  },
  "epochs": 30,
  "path": "./dist",
  "write_retry_limit": 3,
  "site_obj_id": "0xexisting_site_object_id"
}

Signing Options

🔑 ED25519_PRIVATE_KEY

• Default method
• Requires a secret Sui-format private key (suiprivkey...)

🔐 GIT_SIGNER_PIN (Optional)

• Enables remote signing via notary.wal.app/sign
• Keeps signing keys outside of GitHub
• Requires developer to approve signing via secure UI using a PIN

This is ideal for teams or workflows requiring human-in-the-loop signing.

Provenance Workflow

Each deployment:

1. Builds your static site
2. Hashes and signs every file (via GitHub OIDC + Sigstore)
3. Writes a .intoto.jsonl file with full provenance
4. Uploads it with your Walrus site
5. Verifies it via notary.wal.app

You can verify your deployed site at:

https://notary.wal.app/site/your-site-prefix

Replace your-site-prefix with your Walrus Site name (e.g., notary, docs, myproject).

Resources

• 🔗 GitHub Action: walrus-sites-provenance
• 🧾 Example config: site.config.json
• 🌐 Verifier UI: notary.wal.app
• 📘 SLSA: slsa.dev
• 🔐 Sigstore: sigstore.dev