Skip to content

docs: add Filecoin Pin composition example#49

Draft
lidel wants to merge 1 commit intomainfrom
docs/filecoin-pin-example
Draft

docs: add Filecoin Pin composition example#49
lidel wants to merge 1 commit intomainfrom
docs/filecoin-pin-example

Conversation

@lidel
Copy link
Copy Markdown
Contributor

@lidel lidel commented Apr 12, 2026

Important

do not merge, opening to illustrate how we can keep filecoin-pin details separate, without any maintenance burden.

What

Adds a Archiving to Filecoin README section showing how to chain filecoin-project/filecoin-pin/upload-action after this action so the same CAR is archived to Filecoin. No action.yml changes.

Why composition, not embedding

I prototyped embedding Filecoin Pin as a first-class provider and it does not look feasible in current state of upstream code:

  • Complexity. Other providers have CLI which allow us to havee one-liners in action.yml. Filecoin Pin is ~400 lines of Node.js (Synapse, USDFC top-ups, PDP, IPNI, retry). Not sane. We could revisit if upstream provides better CLI tooling that blackboxes process end-to-end.
  • Permissions. Upstream needs checks: write, pull-requests: write, actions: read for its own check run / PR comment / artifact cache. Every caller would have to grant those, even if they never enable Filecoin. Not feasible, bad opsec.
  • Alpha churn. Upstream's README flags the upload-action as an "educational demo" with breaking changes expected. Embedding ties our release cadence to theirs. Maintenance burden.
  • Duplicate PR comments. Upstream already posts its own (piece CID, data set, provider, retrieval URL). Deduping needs another upstream change.

Composition (this PR) scopes all four to users who actually opt in.

Today vs. after upstream #410

Example works today, but upstream repacks the CAR so the Filecoin CID will differ from ours. Once filecoin-project/filecoin-pin#410 ships, switching to path: build.car makes the CIDs identical.

Revisit when

Filecoin Pin ships a shell-level one-liner comparable to ipfs pin remote add (Pinata) or aws s3 cp --metadata 'import=car' (Filebase). Then embedding becomes cheap and the argument flips.

Show users how to chain filecoin-project/filecoin-pin/upload-action
after this action to archive the same CAR to Filecoin, without
repacking or CID drift. Depends on the upstream change that treats
a `.car` `path` as a pre-built CAR (filecoin-project/filecoin-pin#410).
@lidel lidel added need/community-input Needs input from the wider community status/blocked Unable to be worked further until needs are met labels Apr 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

need/community-input Needs input from the wider community status/blocked Unable to be worked further until needs are met

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[placeholder] Add filecoin-pin support (team/filecoin-pin)

1 participant