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

> Automate Swarm deployments and workflows with Swarm Actions in GitHub CI/CD. Publish directly to Swarm from your pipeline for immutable artifact distribution.

- Repository: [Ethersphere/awesome-swarm](https://github.com/ethersphere/awesome-swarm)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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](https://github.com/ethersphere/awesome-swarm/blob/master/README.md#L36). 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/awesome-swarm/blob/main/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/awesome-swarm/blob/main/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`](https://github.com/ethersphere/awesome-swarm/blob/main/.github/workflows/swarm.yml) in your repository root to automate deployments on every push to the main branch:

```yaml
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`](https://github.com/ethersphere/awesome-swarm/blob/main/src/upload.ts) handles authentication, multipart uploads, and hash extraction, while [`action.yml`](https://github.com/ethersphere/awesome-swarm/blob/main/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`](https://github.com/ethersphere/awesome-swarm/blob/main/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.