This template gives your files a CID, a name for exact bytes that anyone can verify and that keeps working wherever the bytes are hosted. A CID is the name of the exact bytes of a file: if the bytes change, the CID changes. It is good for datasets you cite, NFT or dapp assets, software releases, ENS sites.
Here "publish" is what gitpin does, and a "pin" is something published from the pins/ folder in your repo. It is not a copy kept on many machines. Your files are hosted by GitHub Pages, so they are online exactly while your Pages site is; the CID is the lasting part.
If you only want a website, plain GitHub Pages is the better choice and this template is not for you.
Put a file in the pins/ folder, commit, and the gitpin action publishes it to IPFS. IPFS is a network where files are found by their name (their CID) instead of by an address. Every file or folder you put in pins/ gets its own CID, and anyone with that CID can fetch exactly those bytes from the network and verify they match.
The files themselves live on GitHub Pages, so they are online while your Pages site is. To keep a copy elsewhere, add the CID to a pinning service (a paid or free service that keeps copies of files by CID) or to your own IPFS node; the same CID keeps working.
- On github.com/ipni/gitpin-template click "Use this template" > "Create a new repository". Name it exactly
<your-username>.github.io(lowercase is fine) and make it Public. Pages on free accounts needs a public repo. An account can have only one such repo. If you already use yours for a website, adding gitpin to it would replace that website, so use a custom domain instead (see Use a custom domain) or create the repo under a GitHub organization you own. - Open the keygen page, click "Make a key", copy the key.
- In the new repo: Settings > Secrets and variables > Actions > New repository secret, name
GITPIN_KEY, paste, Add secret. - Actions tab > "gitpin" workflow > "Run workflow" (or edit any file in
pins/and commit). The first run creates thegh-pagesbranch, then waits up to 10 minutes for Pages and fails with a message ending in "is not serving the new head yet", because Pages is not serving the branch yet. That is expected. - Settings > Pages > Build and deployment > Source "Deploy from a branch", Branch
gh-pages, folder/ (root), Save. GitHub usually has Pages on already for a repo named<your-username>.github.io, servingmain; the change is only the branch. Saving does not publish anything by itself; the re-run in the next step does. - Re-run the workflow. When it is green, the run summary lists each pin with its CID and links;
https://<your-username>.github.ioshows the same list.
The template ships pins/hello.txt containing Hello from my first IPFS pin!; that is your first pin.
Put a file or folder in pins/ (via "Add file" > "Upload files" on GitHub) and commit. Each top-level file or folder in pins/ is one pin with its own CID.
- Changing a file gives it a new CID, and the old CID's blocks are removed from the site and its record dropped, so an old CID someone cited stops resolving from this site.
- Names starting with
.(such as.gitkeep) are skipped at every level. - Symlinks make the run fail; use real files.
- A pin that is a folder has one directory CID, and each file inside is reachable by path:
https://inbrowser.link/ipfs/<cid>/<name>oripfs cat <cid>/<name>.
https://inbrowser.link/ipfs/<cid>(works in the browser and verifies the content)https://ipfs.io/ipfs/<cid>andhttps://dweb.link/ipfs/<cid>work in a web browser only (they load an in-browser IPFS client); scripts andcurlget an error from them, so use Kubo or the CID with an IPFS library instead.ipfs cat <cid>in a recent Kubo (0.43 or newer was tested; older versions may not fetch over HTTP from a site).
A new pin can take a few minutes, sometimes up to an hour, to show up on cid.contact; until then gateways may not find it. The run then ends with a yellow warning, not a failure.
Delete the file or folder from pins/ and commit. The blocks are removed from the site and cid.contact is told to drop the record.
- Your pins are public. Anyone can fetch them, and the CIDs and your peer ID are listed on cid.contact. Do not publish secrets or personal data.
- This is not durable storage. Your files are online while your GitHub Pages site is. Delete the repo or turn off Pages and they are gone (other IPFS nodes may still hold copies they fetched). To keep a copy elsewhere with the same CID, add the CID to a pinning service or run
ipfs pin add <cid>on your own Kubo node. - At most 500 MiB and 50,000 blocks of content per repo.
- The key signs your advertisements. Keep it only in the
GITPIN_KEYsecret. If it leaks, make a new key, replace the secret, and deletegitpin.jsonand theipni/folder from thegh-pagesbranch before the next run;ipfs/can stay. On GitHub: open thegh-pagesbranch, opengitpin.json, "..." > "Delete file", commit; open theipnifolder, "..." > "Delete directory", commit; or do the same in a local clone and push.
- "... is not serving the new head yet": Pages is off, the source is not set to the
gh-pagesbranch, the repo is private, the repo is not named<owner>.github.ioand nobase-urlis set, or a custom domain is not pointing at Pages yet. - "... redirects to ...": the site redirects, usually because a custom domain is set while
base-urlis still the defaulthttps://<owner>.github.io, or the domain was given as the apex while Pages serveswww(or the other way round); setbase-urlto the exact origin that serves the site. - "The GITPIN_KEY secret is not set": add the secret under Settings > Secrets and variables > Actions.
- "GITPIN_KEY belongs to ... but gitpin.json was written by ...": the key changed; see the key bullet above.
- "needs a repo named
<owner>.github.io": rename the repo, or use a custom domain (see the main README). - A yellow "cid.contact has not indexed every pin yet" warning: wait a few minutes and re-run the workflow.
- The push to
gh-pagesfails: the workflow'sactions/checkoutmust keep its default credentials;persist-credentials: falsebreaks the push that theipni/gitpin@v1action makes.