|
| 1 | +--- |
| 2 | +title: Automate DNSLink updates with GitHub Actions |
| 3 | +description: Guide on how to use the DNSLink Action to automatically update DNS records when deploying static sites to IPFS. |
| 4 | +--- |
| 5 | + |
| 6 | +# Automate DNSLink updates with GitHub Actions |
| 7 | + |
| 8 | +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. |
| 9 | + |
| 10 | +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. |
| 11 | + |
| 12 | +## Prerequisites |
| 13 | + |
| 14 | +Before you begin, make sure you have: |
| 15 | + |
| 16 | +1. Your site deployed to IPFS with a CID (see [Deploy static apps to IPFS with GitHub Actions](./deploy-github-action.md)) |
| 17 | +2. A domain name with DNS managed by a [supported provider](#step-1-configure-dns-provider) (Cloudflare, DNSimple, or Gandi), or any provider via [generic DNS tools](#alternative-generic-dns-tools) |
| 18 | +3. A GitHub repository with Actions enabled |
| 19 | + |
| 20 | +## Security Considerations |
| 21 | + |
| 22 | +::: warning API Token Security |
| 23 | +DNS API tokens are sensitive credentials. A compromised token could allow attackers to modify your DNS records, potentially redirecting your domain to malicious content. |
| 24 | + |
| 25 | +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. |
| 26 | +::: |
| 27 | + |
| 28 | +## Step 1: Configure DNS Provider |
| 29 | + |
| 30 | +The [dnslink-action](https://github.com/ipshipyard/dnslink-action) provides turn-key DNSLink updates with built-in safety features for the providers below. If your provider is not listed, see [Alternative: Generic DNS Tools](#alternative-generic-dns-tools). |
| 31 | + |
| 32 | +### Option A: Cloudflare (recommended) |
| 33 | + |
| 34 | +1. Log into the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your domain |
| 35 | +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)) |
| 36 | +3. Go to **My Profile** > **API Tokens** > **Create Token** ([detailed instructions](https://github.com/ipshipyard/dnslink-action#creating-an-api-token)) |
| 37 | +4. Create a custom token with these permissions: |
| 38 | + - Zone > DNS > Edit |
| 39 | + - Scope the token to your specific zone |
| 40 | +5. Add both values as [GitHub secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions): |
| 41 | + - `CF_ZONE_ID`: Your Zone ID |
| 42 | + - `CF_AUTH_TOKEN`: Your API token |
| 43 | + |
| 44 | +For a visual walkthrough, see the [Cloudflare video tutorial](https://github.com/ipshipyard/dnslink-action#cloudflare-video-tutorial). |
| 45 | + |
| 46 | +### Option B: DNSimple |
| 47 | + |
| 48 | +1. Log into DNSimple and go to **Account** > **Access Tokens** |
| 49 | +2. Create a new API token |
| 50 | +3. Add it as a GitHub secret named `DNSIMPLE_TOKEN` |
| 51 | + |
| 52 | +### Option C: Gandi |
| 53 | + |
| 54 | +1. Log into [Gandi](https://www.gandi.net/) and go to **Account** > **Security** > **Personal Access Tokens** |
| 55 | +2. Create a new token with DNS management permissions |
| 56 | +3. Add it as a GitHub secret named `GANDI_TOKEN` |
| 57 | + |
| 58 | +## Step 2: Add DNSLink Action to Your Workflow |
| 59 | + |
| 60 | +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. |
| 61 | + |
| 62 | +For complete workflow examples, see: |
| 63 | + |
| 64 | +- [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 |
| 65 | +- [Dual workflows (with fork PRs)](https://github.com/ipshipyard/ipfs-deploy-action#dual-workflows-with-fork-prs) - secure pattern for open source projects |
| 66 | + |
| 67 | +For DNS provider-specific configuration, see the [ipshipyard/dnslink-action README](https://github.com/ipshipyard/dnslink-action#usage). |
| 68 | + |
| 69 | +## Step 3: Verify the DNSLink Record |
| 70 | + |
| 71 | +After the workflow runs, verify the DNSLink record: |
| 72 | + |
| 73 | +```bash |
| 74 | +dig +short TXT _dnslink.yourdomain.com |
| 75 | +``` |
| 76 | + |
| 77 | +You should see output like: |
| 78 | + |
| 79 | +``` |
| 80 | +"dnslink=/ipfs/bafybeic..." |
| 81 | +``` |
| 82 | + |
| 83 | +## Alternative: Generic DNS Tools |
| 84 | + |
| 85 | +If your DNS provider is not supported by dnslink-action, or you need more control over DNS updates, you can use generic DNS automation tools in a custom workflow step. |
| 86 | + |
| 87 | +DNSLink is a TXT record on the `_dnslink` subdomain. To update it, set a TXT record on `_dnslink.yourdomain.com` with the value: |
| 88 | + |
| 89 | +``` |
| 90 | +dnslink=/ipfs/<CID> |
| 91 | +``` |
| 92 | + |
| 93 | +Where `<CID>` is the output from [ipshipyard/ipfs-deploy-action](https://github.com/ipshipyard/ipfs-deploy-action). |
| 94 | + |
| 95 | +Tools that support many DNS providers: |
| 96 | + |
| 97 | +- [OctoDNS](https://github.com/octodns/octodns) - supports [many providers](https://octodns.readthedocs.io/en/latest/#providers) including AWS Route53, Google Cloud DNS, Azure DNS, DigitalOcean, and NS1. Can run in CI to sync DNS records from config files. |
| 98 | +- [Terraform DNS providers](https://registry.terraform.io/search/providers?q=dns) - useful if you already manage infrastructure with Terraform. |
| 99 | +- Your provider's API directly via a custom script or GitHub Action step. |
| 100 | + |
| 101 | +## Two-Workflow Pattern for Open Source Projects |
| 102 | + |
| 103 | +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**. |
| 104 | + |
| 105 | +The solution is to separate building (which runs untrusted code) from deploying (which uses secrets): |
| 106 | + |
| 107 | +1. **Build workflow**: Runs on PR events, builds the site, uploads artifact. No secrets. |
| 108 | +2. **Deploy workflow**: Triggered by `workflow_run` event after build succeeds. Has access to secrets but only runs trusted action code, not fork code. |
| 109 | + |
| 110 | +For complete workflow examples, see: |
| 111 | + |
| 112 | +- [ipshipyard/ipfs-deploy-action: Dual workflows with fork PRs](https://github.com/ipshipyard/ipfs-deploy-action#dual-workflows-with-fork-prs) |
| 113 | +- [ipshipyard/dnslink-action: Dual workflows for secure fork PRs](https://github.com/ipshipyard/dnslink-action#dual-workflows-for-secure-fork-prs) |
| 114 | + |
| 115 | +## Security: Sandboxed DNS Zone |
| 116 | + |
| 117 | +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). |
| 118 | + |
| 119 | +### How it works |
| 120 | + |
| 121 | +Instead of giving CI direct access to your domain's DNS: |
| 122 | + |
| 123 | +1. Create a dedicated zone for DNSLink records (e.g., `dnslinks.example.com`) |
| 124 | +2. Create an API token scoped only to that zone |
| 125 | +3. On your main domain, add a CNAME record pointing `_dnslink.yourdomain.com` to `_dnslink.yourdomain.dnslinks.example.com` |
| 126 | +4. The action updates the TXT record on the sandboxed zone |
| 127 | + |
| 128 | +For detailed setup instructions, see the [ipshipyard/dnslink-action security documentation](https://github.com/ipshipyard/dnslink-action#security-sandboxed-dnslink-domain). |
| 129 | + |
| 130 | +## HTTP Hosting |
| 131 | + |
| 132 | +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`. |
| 133 | + |
| 134 | +You have two options: |
| 135 | + |
| 136 | +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). |
| 137 | + |
| 138 | +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. |
| 139 | + |
| 140 | +## Troubleshooting |
| 141 | + |
| 142 | +1. **DNSLink not updating** |
| 143 | + - Verify your API token has DNS edit permissions |
| 144 | + - Check that `dnslink_domain` matches your DNS setup |
| 145 | + - Review the GitHub Actions logs for error messages |
| 146 | + |
| 147 | +2. **DNS propagation delays** |
| 148 | + - DNS changes can take time to propagate |
| 149 | + - Use `dig` to check the authoritative nameserver directly |
| 150 | + |
| 151 | +3. **CNAME not resolving** |
| 152 | + - Ensure the CNAME target includes the full domain name |
| 153 | + - Verify both zones are properly configured |
| 154 | + |
| 155 | +## Getting Help |
| 156 | + |
| 157 | +If you encounter issues: |
| 158 | + |
| 159 | +1. Check the GitHub Actions run logs for detailed error messages |
| 160 | +2. Review the [ipshipyard/dnslink-action README](https://github.com/ipshipyard/dnslink-action) for updates |
| 161 | +3. Open an issue in the [action's repository](https://github.com/ipshipyard/dnslink-action/issues/new) |
0 commit comments