Automating Swarm Deployments and Workflows with Swarm Actions in GitHub CI/CD

Swarm Actions is a ready-made GitHub Action that automates publishing files, directories, and builds to the Swarm network directly from your CI/CD pipeline, returning a permanent content-addressed Swarm hash (BZZ) for immutable artifact distribution.

The ethersphere/awesome-swarm repository lists Swarm Actions as the official CI/CD integration tool for the Swarm decentralized storage network. By implementing this Action in your .github/workflows/ directory, you create reproducible, automated pipelines that push content to Swarm without manual intervention, leveraging the Bee API for content-addressed storage.

What Are Swarm Actions?

Swarm Actions is an external GitHub Action maintained at ethersphere/swarm-actions and referenced in the Awesome-Swarm collection at line 36 of the README.md. The Action encapsulates the Bee client functionality into a containerized environment that runs on GitHub-hosted or self-hosted runners, eliminating the need to manually configure Bee nodes in your local development environment.

The Action executes a Node.js script that authenticates against the Bee API using tokens stored in GitHub Secrets, then uploads artifacts via POST /files or POST /chunks endpoints. This architecture ensures that every build produces deterministic, immutable results—the same source code always generates the identical Swarm hash, enabling verifiable deployments.

Architecture and Workflow Pipeline

Containerized Execution Environment

Each workflow run spins up a clean Ubuntu container (or your specified runs-on environment) that executes the Swarm Action in isolation. This container either initializes a lightweight Bee node internally or connects to an existing external Bee node via the bee-api-url parameter. The ephemeral nature of GitHub Actions guarantees that builds remain reproducible and free from environment drift.

Content Upload and Hash Generation

The Action packages your build artifacts—whether static HTML, Docker manifests, or binary distributions—and transmits them to the Swarm network through the Bee API. Upon successful upload, the Action captures the resulting Swarm reference (BZZ hash) and exposes it as an output variable steps.swarm.outputs.hash, allowing downstream workflow steps to reference the immutable content address for deployment verification or documentation updates.

Implementation Details from Source

Action Configuration (action.yml)

The [action.yml](https://github.com/ethersphere/swarm-actions/blob/master/action.yml) file in the Swarm Actions repository defines the interface between GitHub workflows and the underlying upload logic. This metadata file specifies required inputs including bee-api-url, optional authentication tokens via bee-api-token, and the source directory path containing artifacts to upload. The configuration also declares output parameters that expose the Swarm hash to subsequent workflow steps.

Core Upload Logic (src/upload.ts)

The TypeScript implementation in [src/upload.ts](https://github.com/ethersphere/swarm-actions/blob/master/src/upload.ts) handles the actual communication with the Bee node. This script manages HTTP client initialization, multipart form construction for file uploads, and response parsing to extract the content identifier. The implementation supports both direct chunk uploads for raw data and manifest-based uploads for structured directories, automatically selecting the appropriate API endpoint based on source content type.

Practical Implementation Guide

Complete Workflow Example

Add the following configuration to .github/workflows/swarm.yml in your repository root to automate deployments on every push to the main branch:

name: Deploy to Swarm

on:
  push:
    branches: [ main ]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      # 1️⃣ Check out the repository

      - uses: actions/checkout@v4

      # 2️⃣ Set up Node (required by the Swarm Action)

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      # 3️⃣ Install project dependencies & build artefacts

      - name: Install & Build
        run: |
          npm ci
          npm run build   # produces ./dist/

      # 4️⃣ Upload to Swarm using the official Swarm Action

      - name: Upload to Swarm
        id: swarm
        uses: ethersphere/swarm-actions@v1
        with:
          bee-api-url: ${{ secrets.BEE_API_URL }}   # e.g. http://localhost:1633

          bee-api-token: ${{ secrets.BEE_API_TOKEN }}   # optional, if your Bee node requires auth

          source: ./dist/
          # optional: set a custom manifest title

          manifest-title: "My Awesome Site"

      # 5️⃣ Echo the resulting Swarm hash

      - name: Show Swarm hash
        run: echo "Swarm hash: ${{ steps.swarm.outputs.hash }}"

Required Secrets Configuration

Store sensitive configuration in your repository's GitHub Secrets to prevent API credential exposure. The BEE_API_URL parameter points to your Bee node endpoint (local development nodes typically use http://localhost:1633, while production deployments may specify remote URLs). The optional BEE_API_TOKEN enables authentication for protected Bee nodes, ensuring only authorized CI pipelines can publish to your Swarm gateway.

Production Use Cases

Static Site Hosting

Configure Swarm Actions to deploy Jekyll, Next.js, or vanilla HTML builds directly to the decentralized web. The resulting BZZ hash serves as a permanent URL resistant to censorship or server downtime, while the Action can trigger on every commit to automatically update your Swarm-hosted website.

Immutable Package Publishing

Distribute npm packages, Docker image manifests, or release binaries as Swarm manifests during tag creation events. By setting the workflow trigger to on: push: tags: - 'v*', you ensure that every semantic version release receives a unique, immutable Swarm reference that package managers or download scripts can reference permanently.

Summary

• Swarm Actions automates Swarm uploads through a containerized GitHub Action available at ethersphere/swarm-actions, listed in the Awesome-Swarm ecosystem.
• The Action communicates via the Bee API using POST /files or POST /chunks endpoints to generate content-addressed BZZ hashes.
• Configure workflows in .github/workflows/ using the ethersphere/swarm-actions@v1 reference, supplying bee-api-url and optional bee-api-token from GitHub Secrets.
• The TypeScript core in src/upload.ts handles authentication, multipart uploads, and hash extraction, while action.yml defines the interface contract.
• Implement this for static site deployment, immutable package distribution, or CI validation to ensure reproducible, decentralized builds.

Frequently Asked Questions

How do I connect Swarm Actions to my existing Bee node rather than spawning a new one?

Specify your Bee node's HTTP API endpoint in the bee-api-url input parameter, typically stored as BEE_API_URL in GitHub Secrets. The Action will route all upload requests to this external endpoint instead of initializing an internal node, allowing you to use persistent, funded nodes with existing stamp batches.

What file types and sizes does Swarm Actions support?

The Action supports any file type or directory structure that the underlying Bee client accepts, including static HTML, JavaScript bundles, binary executables, and container manifests. Size limitations depend on your Bee node's available storage and postage stamp value rather than the Action itself, as the TypeScript implementation in src/upload.ts streams data via standard HTTP multipart uploads.

Can I use Swarm Actions in private repositories or with self-hosted runners?

Yes, the Action functions identically in private repositories and supports self-hosted GitHub Actions runners. When using self-hosted infrastructure, ensure the runner environment has network access to your specified bee-api-url and that the Node.js runtime (version 20 or compatible) is available, as the Action relies on the actions/setup-node foundation for dependency management.

How do I retrieve the Swarm hash for use in subsequent workflow steps?

Reference the Action's output using the syntax ${{ steps.swarm.outputs.hash }} where swarm matches the id assigned in the upload step. This output variable contains the complete BZZ reference that you can pass to notification scripts, deployment verification tools, or PR comment automation to share the immutable content address with stakeholders.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}