add-to-web3

July 7, 2025 · View on GitHub

Upload files to Storacha from a Github Action, and output the IPFS Content ID.

A lightweight wrapper around the Storacha CLI tool. As a composite github action all it does is configure and call the cli for you. See the steps in ./action.yml.

Usage

uses: storacha/add-to-web3@v4
id: storacha
with:
  path_to_add: 'dist'
  proof: ${{ secrets.STORACHA_PROOF }}
  secret_key: ${{ secrets.STORACHA_PRINCIPAL }}

# use the outputs in subsequent steps
# "bafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbauguluen5v6am"
- run: echo ${{ steps.storacha.outputs.cid }}

# "https://bafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbauguluen5v6am.ipfs.w3s.link"
- run: echo ${{ steps.storacha.outputs.url }}

Generating a `secret_key` and `proof`

On your dev machine, use the Storacha CLI tool to generate a secret_key and proof to allow this action to upload to a space.

Install it from npm and login as described here docs.storacha.network/quickstart then create a key like this:

# Use the `did` in the input to the next command. 
# Use `key` as your `secret_key` for add_to_web3.
$ storacha key create --json
{
  "did": "did:key:z6Mk...",
  "key": "MgCaT7Se2QX9..."
}

Keep the key safe. Save it as a secret on your repo.

Copy the did for use in the next command. The output is a base64 encoded ucan proof that delegates capabilities to space/blob/add, space/index/add, filecoin/offer, and upload/add on your current space to the key generated above.

# Delegate capabilities to the `did` we created above.
$ storacha delegation create did:key:z6Mk... -c space/blob/add -c space/index/add -c filecoin/offer -c upload/add --base64
mAYIEAP8OEaJlcm9vdHOAZ3ZlcnNpb24BwwUBcRIg+oHTbzShh1WzBo9ISkonCW+KAcy/+zW8Zb...

The capabilies space/blob/add, space/index/add, filecoin/offer, and upload/add are the minimum required to upload files to web3.storage. This proof will not allow that key to list uploads in this space for example.

To recap:

Use the key value from the output of storacha key create --json as the secret_key for this action.
Use the did value from that output as the audience for storacha delegation create <audience> shown above.
Use the output of storacha delegation create <audience> --base64 as the proof for this action.

Inputs

`path_to_add`

Required The path the root directory of your static website or other content that you want to publish to IPFS.

`secret_key`

Required The base64 encoded key to use to sign UCAN invocations to web3.storage.

Create one using storacha key create. See: https://github.com/storacha/upload-service/tree/main/packages/cli#storacha_principal

`proof`

Required A base64 encoded UCAN delegating capabilities the signing key above.

Create a proof using w3cli, delegating space/blob/add, space/index/add, filecoin/offer, and upload/add

$ AUDIENCE_DID="<the DID for secret_key created by `storacha key create`>"
$ storacha delegation create $AUDIENCE_DID  -c space/blob/add -c space/index/add -c filecoin/offer -c upload/add --base64`