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.