Archive IPFS content to Filecoin via filecoin-pin

filecoin-pin uploads IPFS content to Filecoin Onchain Cloud (Synapse) over PDP, topping up USDFC from a wallet when needed. It uses CAR files internally as its bundle format, so filecoin-pin import takes the file that ipfs-deploy-action produces as-is and the root CID stays the same end-to-end.

The upstream CLI recipe is the source of truth for running the CLI in CI: wallet setup, spend caps, version pinning, network selection, and egress. This page covers only the wiring specific to ipfs-deploy-action.

Prerequisites

• A Filecoin wallet private key in a repository secret (e.g. FILECOIN_WALLET_KEY). The wallet must hold USDFC for funding storage details. See the Filecoin Onchain Cloud documentation for more information about USDFC.
• Spend caps --min-runway-days and --max-balance. See the upstream recipe for how to choose them.

Recipe

- name: Create IPFS CAR
  uses: ipfs/ipfs-deploy-action@v2
  id: deploy
  with:
    path-to-deploy: 'out'
    cid-profile: 'unixfs-v1-2025'  # IPIP-0499; switch to 'unixfs-v0-2015' only if you need legacy CIDv0
    github-token: ${{ github.token }}

- name: Archive to Filecoin
  env:
    PRIVATE_KEY: ${{ secrets.FILECOIN_WALLET_KEY }}
    CAR_PATH: ${{ steps.deploy.outputs.car-path }}
  run: |
    npx -y filecoin-pin@0.22.3 import "$CAR_PATH" \
      --network mainnet \
      --auto-fund \
      --min-runway-days 30 \
      --max-balance 5.0

The path to import comes from steps.deploy.outputs.car-path; the root CID is steps.deploy.outputs.cid. Add Kubo or IPFS Cluster inputs to the deploy step to also pin to your own infrastructure; see the main README.

Notes

• Gate this step yourself. It spends wallet funds, so decide where it runs before adding it: typically push to your default branch, or the secrets-bearing half of a dual workflow.
• Use --network calibration for testnet runs. There is no --mainnet / --calibnet shorthand.