Writing your workflow

Now that you have configured your secrets and variables, you can create GitHub workflows to automate your Walrus Site deployments using the official "Deploy Walrus Site" GitHub Action.

Key Requirement: Pre-built Site Directory

The Deploy Walrus Site action operates on an already built site directory. The action does not build your site - it deploys existing static files to Walrus.

This means:

• If your site consists of ready-to-deploy static files (HTML, CSS, JS), you can use the action directly
• If your site requires a build step (React, Vue, Svelte, etc.), you must include build steps in your workflow before calling the deploy action

Using the Deploy Walrus Site GitHub Action

The action (MystenLabs/walrus-sites/.github/actions/deploy) requires these inputs:

• SUI_ADDRESS: Your Sui address (GitHub variable)
• SUI_KEYSTORE: Your private key in base64 format (GitHub secret)
• DIST: Path to your built site directory

Optional inputs include:

• SUI_NETWORK: Target network (mainnet or testnet, defaults to mainnet)
• EPOCHS: Number of epochs to keep the site stored (defaults to 5)
• WALRUS_CONFIG: Custom Walrus configuration (downloads default if not provided)
• SITES_CONFIG: Custom sites configuration (downloads default if not provided)
• WS_RESOURCES: Full path to the ws-resources.json file (defaults to DIST/ws-resources.json)
• GITHUB_TOKEN: Enables automatic pull request creation when site resources change

About GITHUB_TOKEN

The GITHUB_TOKEN input is particularly useful for tracking changes to your site's resources. When you deploy a site, site-builder creates or updates a ws-resources.json file that tracks the site's data. If this file changes during deployment, the action can automatically create a pull request with the updated file.

To use this feature:

1. Set GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} in your workflow

2. Add these permissions to your workflow:

   permissions:
     contents: write
     pull-requests: write
   

New Site vs Existing Site

Understanding how the workflow behaves depends on whether you have an existing site:

New site (no existing object_id):

• Creates a new Walrus Site on Sui.
• Generates a ws-resources.json file in your DIST directory (or updates the file specified by WS_RESOURCES).
• This file contains the object_id of your newly created site.
• If GITHUB_TOKEN is provided with correct permissions, creates a pull request with these changes.

Existing site (has object_id):

• Uses the existing object_id from your Walrus-Sites resources file to update the same site.
• Only creates PRs if the resources file changes during deployment.
• This applies whether you've previously deployed using GitHub Actions or manually using the CLI - as long as the object_id is present in your WS_RESOURCES file (defaults to DIST/ws-resources.json)

Creating Your Workflow

1. Create .github/workflows/deploy-site.yml in your repository
2. Add checkout step to get your repository files
3. If your site needs building, add build steps:
   • Add build environment setup (Node.js, etc.)
   • Add build commands
4. Set your DIST path:
   • For sites requiring build: Point to your build output directory (e.g., dist/, build/)
   • For static sites: Point directly to your static files directory
5. Add the Deploy Walrus Site action with your configured secrets and variables

The key is ensuring your DIST path points to a directory containing the final, deployable static files that should be published to Walrus.

Example Workflows

• deploy-snake.yml - Simple static site deployment
• deploy-vite-react-ts.yml - React application with build step

For more information about creating and configuring GitHub workflows, check the official GitHub Actions documentation.