docs: add dnslink-action guide and update related pages

lidel · lidel · commit fa5fb4c78fa2 · 2026-01-06T23:26:00.000+01:00
- add new guide for automating DNSLink updates with GitHub Actions
- fix ipfs-deploy-action namespace (ipfs -&gt; ipshipyard)
- add next steps section to deploy-github-action guide
- update custom-domains and dnslink-gateway with links to new guide
- add dnslink-action to navigation
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -257,6 +257,7 @@ module.exports = {
               collapsable: true,
               children: [
                 '/how-to/websites-on-ipfs/deploy-github-action',
+                '/how-to/websites-on-ipfs/dnslink-action',
                 '/how-to/websites-on-ipfs/custom-domains',
                 '/how-to/websites-on-ipfs/single-page-website',
                 '/how-to/websites-on-ipfs/dnslink-gateway',
diff --git a/docs/how-to/websites-on-ipfs/custom-domains.md b/docs/how-to/websites-on-ipfs/custom-domains.md
@@ -41,5 +41,5 @@ With this approach, users can access your website via a custom domain name, e.g.
 To provide access to the app directly via the custom domain, you have the following options:
 
 1. Self-host both the IPFS provider (e.g. [Kubo](https://github.com/ipfs/kubo)) and the IPFS HTTP gateway (e.g. [Kubo](https://github.com/ipfs/kubo)). Deploy an IPFS Gateway that supports DNSLink resolution and point the `CNAME`/`A` DNS record for your custom domain to it and update the `TXT` record on `_dnslink` subdomain to match CID of your website. [See the guide on setting up a DNSLink gateway](./dnslink-gateway.md) for more details.
-2. Deploy the site to a web hosting service like [Cloudflare Pages](https://pages.cloudflare.com/) or [GitHub Pages](https://pages.github.com/) with a custom domain (pointing and configuring the `CNAME`/`A` record for your custom domain on the web hosting service), while managing the DNSLink `TXT` record on `_dnslink` subdomain separately, essentially getting the benefits of both IPFS and traditional web hosting. Remember to set up CI automation to update the DNSLink `TXT` record for every deployment that changes the CID.
+2. Deploy the site to a web hosting service like [Cloudflare Pages](https://pages.cloudflare.com/) or [GitHub Pages](https://pages.github.com/) with a custom domain (pointing and configuring the `CNAME`/`A` record for your custom domain on the web hosting service), while managing the DNSLink `TXT` record on `_dnslink` subdomain separately, essentially getting the benefits of both IPFS and traditional web hosting. Use the [DNSLink Action](./dnslink-action.md) to automatically update the DNSLink `TXT` record for every deployment that changes the CID. If you prefer to run your own HTTP server, see [Setup a DNSLink Gateway with Kubo and Caddy](./dnslink-gateway.md).
 
diff --git a/docs/how-to/websites-on-ipfs/deploy-github-action.md b/docs/how-to/websites-on-ipfs/deploy-github-action.md
@@ -130,7 +130,7 @@ jobs:
         run: npm run build
 
       - name: Deploy to IPFS
-        uses: ipfs/ipfs-deploy-action@v1
+        uses: ipshipyard/ipfs-deploy-action@v1
         id: deploy
         with:
           path-to-deploy: dist # Change this to your build output directory
@@ -156,7 +156,7 @@ To upload the CAR file to a Kubo node instead of or in addition to Storacha:
 
 ```yaml
 - name: Deploy to IPFS
-  uses: ipfs/ipfs-deploy-action@v1
+  uses: ipshipyard/ipfs-deploy-action@v1
   with:
     # ... other inputs ...
     kubo-api-url: ${{ secrets.KUBO_API_URL }}
@@ -167,7 +167,7 @@ You can also customize the Kubo version and [`ipfs add` parameters](https://docs
 
 ```yaml
 - name: Deploy to IPFS
-  uses: ipfs/ipfs-deploy-action@v1
+  uses: ipshipyard/ipfs-deploy-action@v1
   with:
     # ... other inputs ...
     kubo-version: 'v0.39.0' # Default, change if needed
@@ -184,7 +184,7 @@ To upload the CAR file to an IPFS Cluster:
 
 ```yaml
 - name: Deploy to IPFS
-  uses: ipfs/ipfs-deploy-action@v1
+  uses: ipshipyard/ipfs-deploy-action@v1
   with:
     # ... other inputs ...
     cluster-url: ${{ secrets.CLUSTER_URL }}
@@ -196,7 +196,7 @@ You can also configure additional IPFS Cluster options:
 
 ```yaml
 - name: Deploy to IPFS
-  uses: ipfs/ipfs-deploy-action@v1
+  uses: ipshipyard/ipfs-deploy-action@v1
   with:
     # ... other inputs ...
     cluster-retry-attempts: '5' # Override number of retry attempts
@@ -217,7 +217,7 @@ To pin your content to Pinata:
 
 ```yaml
 - name: Deploy to IPFS
-  uses: ipfs/ipfs-deploy-action@v1
+  uses: ipshipyard/ipfs-deploy-action@v1
   with:
     # ... other inputs ...
     pinata-jwt-token: ${{ secrets.PINATA_JWT_TOKEN }}
@@ -236,7 +236,7 @@ To store CAR files on Filebase:
 
 ```yaml
 - name: Deploy to IPFS
-  uses: ipfs/ipfs-deploy-action@v1
+  uses: ipshipyard/ipfs-deploy-action@v1
   with:
     # ... other inputs ...
     filebase-bucket: 'your-bucket-name'
@@ -295,6 +295,14 @@ This URL uses subdomain resolution (where the CID has its own subdomain), which
 3. Consider using multiple IPFS providers for redundancy
 4. Use environment-specific configurations when needed
 
+## Next Steps
+
+After deploying your site to IPFS, you may want to:
+
+- **Add a custom domain**: Use [DNSLink](./dnslink-action.md) to automatically update DNS records so users can access your site via a human-readable domain name like `yourdomain.com` instead of a CID.
+- **Set up a DNSLink gateway**: If you want to serve your site directly from your own domain over HTTPS, see [Setup a DNSLink Gateway](./dnslink-gateway.md).
+- **Learn about custom domains**: For an overview of domain options, see [Custom domains and DNSLink](./custom-domains.md).
+
 ## Getting Help
 
 If you encounter any issues:
diff --git a/docs/how-to/websites-on-ipfs/dnslink-action.md b/docs/how-to/websites-on-ipfs/dnslink-action.md
@@ -0,0 +1,141 @@
+---
+title: Automate DNSLink updates with GitHub Actions
+description: Guide on how to use the DNSLink Action to automatically update DNS records when deploying static sites to IPFS.
+---
+
+# Automate DNSLink updates with GitHub Actions
+
+This guide explains how to automatically update [DNSLink](../../concepts/dnslink.md) records when you deploy your site to IPFS. By the end, your DNS will automatically point to the latest CID whenever you push to your repository.
+
+DNSLink lets users access your IPFS-hosted content through a human-readable domain name like `docs.ipfs.tech` instead of a CID like `bafybeic...`. When combined with [ipshipyard/ipfs-deploy-action](./deploy-github-action.md), you get a complete CI/CD pipeline for IPFS websites.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+1. Your site deployed to IPFS with a CID (see [Deploy static apps to IPFS with GitHub Actions](./deploy-github-action.md))
+2. A domain name with DNS managed by [Cloudflare](https://www.cloudflare.com/), [DNSimple](https://dnsimple.com/), or [Gandi](https://www.gandi.net/en/domain/dns)
+3. A GitHub repository with Actions enabled
+
+## Security Considerations
+
+::: warning API Token Security
+DNS API tokens are sensitive credentials. A compromised token could allow attackers to modify your DNS records, potentially redirecting your domain to malicious content.
+
+For open source projects that accept pull requests from forks, use the [two-workflow pattern](#two-workflow-pattern-for-open-source-projects) to ensure fork code never has access to your DNS credentials.
+:::
+
+## Step 1: Configure DNS Provider
+
+### Option A: Cloudflare (recommended)
+
+1. Log into the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your domain
+2. Go to the **Overview** tab and scroll down to find your **Zone ID** ([detailed instructions](https://github.com/ipshipyard/dnslink-action#finding-your-zone-id))
+3. Go to **My Profile** > **API Tokens** > **Create Token** ([detailed instructions](https://github.com/ipshipyard/dnslink-action#creating-an-api-token))
+4. Create a custom token with these permissions:
+   - Zone > DNS > Edit
+   - Scope the token to your specific zone
+5. Add both values as [GitHub secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions):
+   - `CF_ZONE_ID`: Your Zone ID
+   - `CF_AUTH_TOKEN`: Your API token
+
+For a visual walkthrough, see the [Cloudflare video tutorial](https://github.com/ipshipyard/dnslink-action#cloudflare-video-tutorial).
+
+### Option B: DNSimple
+
+1. Log into DNSimple and go to **Account** > **Access Tokens**
+2. Create a new API token
+3. Add it as a GitHub secret named `DNSIMPLE_TOKEN`
+
+### Option C: Gandi
+
+1. Log into [Gandi](https://www.gandi.net/) and go to **Account** > **Security** > **Personal Access Tokens**
+2. Create a new token with DNS management permissions
+3. Add it as a GitHub secret named `GANDI_TOKEN`
+
+## Step 2: Add DNSLink Action to Your Workflow
+
+Add [ipshipyard/dnslink-action](https://github.com/ipshipyard/dnslink-action) to your workflow after deploying to IPFS. The action takes the CID from [ipshipyard/ipfs-deploy-action](https://github.com/ipshipyard/ipfs-deploy-action) and updates your DNS record.
+
+For complete workflow examples, see:
+
+- [Simple workflow (no fork PRs)](https://github.com/ipshipyard/ipfs-deploy-action#simple-workflow-no-fork-prs) - single workflow for repositories that don't accept external contributions
+- [Dual workflows (with fork PRs)](https://github.com/ipshipyard/ipfs-deploy-action#dual-workflows-with-fork-prs) - secure pattern for open source projects
+
+For DNS provider-specific configuration, see the [ipshipyard/dnslink-action README](https://github.com/ipshipyard/dnslink-action#usage).
+
+## Step 3: Verify the DNSLink Record
+
+After the workflow runs, verify the DNSLink record:
+
+```bash
+dig +short TXT _dnslink.yourdomain.com
+```
+
+You should see output like:
+
+```
+"dnslink=/ipfs/bafybeic..."
+```
+
+## Two-Workflow Pattern for Open Source Projects
+
+For repositories that accept pull requests from forks, use a two-workflow pattern to keep secrets secure. This is critical because **pull requests from forks can contain malicious code that could exfiltrate your secrets**.
+
+The solution is to separate building (which runs untrusted code) from deploying (which uses secrets):
+
+1. **Build workflow**: Runs on PR events, builds the site, uploads artifact. No secrets.
+2. **Deploy workflow**: Triggered by `workflow_run` event after build succeeds. Has access to secrets but only runs trusted action code, not fork code.
+
+For complete workflow examples, see:
+
+- [ipshipyard/ipfs-deploy-action: Dual workflows with fork PRs](https://github.com/ipshipyard/ipfs-deploy-action#dual-workflows-with-fork-prs)
+- [ipshipyard/dnslink-action: Dual workflows for secure fork PRs](https://github.com/ipshipyard/dnslink-action#dual-workflows-for-secure-fork-prs)
+
+## Security: Sandboxed DNS Zone
+
+For additional security, use a sandboxed DNS zone to limit what the CI API token can modify. This way, if the token is compromised, attackers can only modify TXT records on a dedicated zone, not your main domain's DNS records (like A, MX, or NS records).
+
+### How it works
+
+Instead of giving CI direct access to your domain's DNS:
+
+1. Create a dedicated zone for DNSLink records (e.g., `dnslinks.example.com`)
+2. Create an API token scoped only to that zone
+3. On your main domain, add a CNAME record pointing `_dnslink.yourdomain.com` to `_dnslink.yourdomain.dnslinks.example.com`
+4. The action updates the TXT record on the sandboxed zone
+
+For detailed setup instructions, see the [ipshipyard/dnslink-action security documentation](https://github.com/ipshipyard/dnslink-action#security-sandboxed-dnslink-domain).
+
+## HTTP Hosting
+
+DNSLink maps a domain name to a CID, so IPFS gateways can serve your content. You also need HTTP hosting for users who access your site directly via `https://yourdomain.com`.
+
+You have two options:
+
+1. **Self-hosted**: Run your own Kubo + Caddy setup that resolves DNSLink and serves content over HTTPS. See [Setup a DNSLink Gateway](./dnslink-gateway.md).
+
+2. **Third-party hosting**: Deploy to [GitHub Pages](https://pages.github.com/), [Cloudflare Pages](https://pages.cloudflare.com/), or [Netlify](https://www.netlify.com/). These handle HTTP hosting independently, while DNSLink provides IPFS access for users with local nodes or gateways.
+
+## Troubleshooting
+
+1. **DNSLink not updating**
+   - Verify your API token has DNS edit permissions
+   - Check that `dnslink_domain` matches your DNS setup
+   - Review the GitHub Actions logs for error messages
+
+2. **DNS propagation delays**
+   - DNS changes can take time to propagate
+   - Use `dig` to check the authoritative nameserver directly
+
+3. **CNAME not resolving**
+   - Ensure the CNAME target includes the full domain name
+   - Verify both zones are properly configured
+
+## Getting Help
+
+If you encounter issues:
+
+1. Check the GitHub Actions run logs for detailed error messages
+2. Review the [ipshipyard/dnslink-action README](https://github.com/ipshipyard/dnslink-action) for updates
+3. Open an issue in the [action's repository](https://github.com/ipshipyard/dnslink-action/issues/new)
diff --git a/docs/how-to/websites-on-ipfs/dnslink-gateway.md b/docs/how-to/websites-on-ipfs/dnslink-gateway.md
@@ -185,7 +185,13 @@ Your gateway will now automatically serve the content specified in the `_dnslink
 
 ## Automate DNSLink Updates
 
-Depending on how you deploy your site, you can automate DNSLink updates using the [DNSLink GitHub Action](https://github.com/ipshipyard/dnslink-action), as part of your CI/CD pipeline, or other DNS management tools like [dnscontrol](https://github.com/StackExchange/dnscontrol) or [octodns](https://github.com/octodns/octodns).
+Depending on how you deploy your site, you can automate DNSLink updates using the [DNSLink Action](./dnslink-action.md) as part of your CI/CD pipeline. For a step-by-step guide, see [Automate DNSLink updates with GitHub Actions](./dnslink-action.md).
+
+::: tip Security Best Practice
+For production deployments, consider using a [sandboxed DNS zone](./dnslink-action.md#security-sandboxed-dns-zone) to limit what your CI API token can modify. This way, if credentials are compromised, attackers can only modify the DNSLink TXT record, not other DNS records like A, MX, or NS.
+:::
+
+You can also use other DNS management tools like [dnscontrol](https://github.com/StackExchange/dnscontrol) or [octodns](https://github.com/octodns/octodns).
 
 ## Troubleshooting
 
