How to Upload from CI

Publish files to IPFS and Filecoin via Storacha from a Continuous Integration server.

Using the CLI locally, the steps are:

Create a space that you want CI to upload to (or use an existing one)
Create a signing key for CI to use with storacha key create
Create a proof that delegates capabilities to upload to your space to that key

Then in the CI environment:

Install the CLI tool from npm
Import the signing key by setting it as STORACHA_PRINCIPAL in the env
Import the proof by passing it to storacha space add
Upload your files with storacha up

Using Github? Use the add-to-web3 Action https://github.com/marketplace/actions/add-to-web3 (opens in a new tab)

Example

Using the CLI, create a signing key and a proof:

# Create key and did. Use the output `key` value as STORACHA_PRINCIPAL in CI.
$ storacha key create --json > ci-key.json
 
# Extract the did as $AUDIENCE
$ AUDIENCE=$(jq -r .did ci-key.json)
 
# Create a signed proof that you delegate capabilties to that key. 
$ storacha delegation create $AUDIENCE -c space/blob/add -c space/index/add -c filecoin/offer -c upload/add --base64
mAYIEAP8OEaJlcm9vdHOAZ3ZlcnNpb24BwwUBcRIg+oHTbzShh1WzBo9ISkonCW+KAcy/+zW8Zb...
 
# Pass the output to `storacha space add` in ci

Then on the CI side (in github flavour (opens in a new tab))

steps:
  - run: npm install -g @storacha/cli
 
  - run: storacha space add ${{ inputs.proof }}
    env:
      STORACHA_PRINCIPAL: ${{ inputs.secret_key }}
 
  - run: storacha up ${{ inputs.path_to_add }}
    env:
      STORACHA_PRINCIPAL: ${{ inputs.secret_key }}

The rest of this document explains the process in more detail.

Create a space

On your local machine with the Storacha CLI (opens in a new tab) installed and logged in (see: /quickstart/) run

$ storacha space create

and follow the instructions. (See: /how-to/create-space/#using-the-cli if you get stuck.)

If you want to use an existing space, make sure it is set as your current space using storacha space ls and storacha space use

Create a signing key

On your local machine, use the Storacha CLI (opens in a new tab) to generate a new a new Ed25519 private signing key for CI to use.

# 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. It will be used by CI to sign requests to Storacha.

The did from the command above is the public decentralized identifier for that private key.

Create a proof

On your local machine, use the Storacha CLI (opens in a new tab) to delegate capabilties to upload to our space to the public DID for the signing key we created.

Our CI environment doesn't need to list our uploads or change our billing plan so we only delegate the space/blob/add, space/index/add, filecoin/offer and upload/add capabilities to it.

Pass the did for the signing key as the audience parameter. We are delegating capabilities to that key.

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

The output is a base64 encoded UCAN proof, signed by your local key. It can only be used as proof by the signing key we specified by the DID we passed in.

Now we have a signing key and a proof we can use in the CI environment.

Install the Storacha CLI in CI

Install it from npm with the --global flag to make the storacha command available.

$ npm i --global @storacha/cli

Import the signing key

Set STORACHA_PRINCIPAL=<the signing key> in the CI environment. The storacha commmand will use the value as the signing key to use. see: https://github.com/storacha/upload-service/tree/main/packages/cli#storacha\_principal (opens in a new tab)

The value is the key we created above with storacha key create. The key must be the one for the did that was used to create the proof.

Import the proof

Set STORACHA_PROOF=<the proof> in the CI environment.

In your CI job definition, run the storacha space add command to import the proof that it can upload to the space we created.

$ storacha space add $STORACHA_PROOF

Upload your files

In your CI job definition, run the storacha up command to upload the files you want to publish on IPFS and store in Filecoin.

$ storacha up <path to files>

that path might be the dist or output directory of a previous step that built your static website or collected some stats from a job.

Once that command returns succesfully, you are done, your files are content addressed and available over IPFS.

If you want to capture the CID for your uploads pass the --json flag and use jq to extract it

# write the output as json to a file
$ storacha up <path to files> --json > ./storacha_up_output.json
 
# extract the root cid from the output and set it as an env var.
$ CID=$(jq --raw-output '.root."/"' ./storacha_up_output.json)

Github Action: add-to-web3

The add-to-web3 (opens in a new tab) action is a lightweight wrapper around the Storacha CLI (opens in a new tab). You create the key and proof as before, and the action configures and runs storacha in CI for you.

Use it in your Github Workflow like this

uses: storacha/add-to-web3@v3
id: storacha
with:
  path_to_add: 'dist'
  secret_key: ${{ secrets.STORACHA_PRINCIPAL }}
  proof: ${{ secrets.STORACHA_PROOF }}
 
# use the outputs in subsequent steps
# "bafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbauguluen5v6am"
- run: echo ${{ steps.storacha.outputs.cid }}
 
# "https://bafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbauguluen5v6am.ipfs.storacha.link"
- run: echo ${{ steps.storacha.outputs.url }}

It uploads path_to_add to Storacha.

It outputs the root CID as cid and IPFS Gateway URL as url for subsequent steps in your workflow to use.

Publish IPNS names HTTP Bridge