Connect a custom-coded site through GitHub (Next.js, Astro, Hugo, HTML)
Updated
Is this the right connection for you?#
- Yes if your site is built with Next.js, Astro, Hugo, Jekyll, Eleventy, Gatsby, Docusaurus, Nuxt, Contentlayer, ASP.NET Core or plain HTML, and its code lives on GitHub. It does not matter where it is hosted (Vercel, Netlify, Cloudflare Pages and so on).
- No if your pages are written in a content system like Contentful, Sanity or Strapi. Connect that instead: see connect other platforms.
- No if your code is on GitLab, Bitbucket or only on your computer. Your agents then hand you each fix as ready-to-paste code. See copy and paste fixes.
Connect your repository#
- In the sidebar, under Setup, click Connections. On the GitHub row, click Add Connection.
- Read what the agent can do, then click Continue with GitHub.
- On GitHub, install the SEOmatic AI app. Choose Only select repositories and pick the repository that holds your website. The app asks for access to code and pull requests on that repository only.
- Back in SEOmatic, under Repository that holds your website, click your repository.
- In Live site URL, type your public address, like
https://yoursite.com. - Click Connect repository. A message says GitHub connected. The agent now delivers edits as pull requests.
SEOmatic then maps which file builds which page. Your agents plan their first fixes once that map is ready. You need write access to the repository: repositories you cannot push to are greyed out with You need write access to this repository.
Your default branch is never touched
SEOmatic cannot commit to your main branch. Every change is a pull request on its own branch. To stop at any time, uninstall the SEOmatic AI app from your repository on GitHub. Open pull requests stay yours.
What your agents can change#
| File type | What a pull request can change |
|---|---|
| HTML pages | Title, meta description, canonical, noindex, structured data, and the text inside the page's main area |
| Markdown posts | Title and description in the frontmatter. Canonical and noindex where your theme reads them. Never the URL |
| Next.js and Astro pages | Title, description, canonical, noindex and structured data, where the code shows the page renders them |
| ASP.NET Core (Razor) | Title, description, canonical and structured data in your templates. Content stored in a database is not edited |
| New articles | A new markdown file in your content folder, with the same fields as your other posts |
| Site-wide fixes | Sitemap, robots.txt and redirects. Your first one opens as a draft pull request |
After you merge#
About 2 minutes after you merge, SEOmatic checks your live page for the exact change, and keeps checking every 5 minutes for about half an hour. Only then is the fix marked live. If you close a pull request without merging, that fix is dismissed.
If you see Merged, but your live page still does not show the change after about half an hour of checking, check that your host rebuilt the site, that the deploy did not fail, and that it publishes from the branch you merged into.
Fix connection errors#
| You see | What to do |
|---|---|
| Your GitHub organization owner needs to approve SEOmatic... | Ask an owner of your GitHub organization to approve the app, then click Continue with GitHub again. |
| SEOmatic cannot see any repositories you have access to... | Click Open GitHub settings, give the SEOmatic AI app access to your website's repository, then try again. |
| Your repository is not in the list | Click Give SEOmatic access to it on GitHub under the list. |
| This repository is archived on GitHub... | Unarchive it on GitHub, or pick another repository. |
| The GitHub step took longer than an hour... | Click Continue with GitHub. You pick up where you left off. |
| That GitHub installation is not on the GitHub account you are signed in with... | Sign in to GitHub as the account that installed SEOmatic, then try again. |
| Your role in this workspace cannot add connections... | Ask a workspace Owner or Admin to connect GitHub. |
- My site is on Vercel. Do I connect Vercel?
- No. Connect the GitHub repository Vercel deploys from. When you merge a pull request, Vercel rebuilds your site as usual.
- Can I check SEO on my own pull requests too?
- Yes. In Settings, the GitHub checks section adds an SEO check to pull requests. By default it reports only.
- Does reconnecting lose anything?
- Reconnecting the same repository keeps the page map and history. Picking a different repository starts a new map.
Was this article helpful?
Still need help?Email contact@seomatic.ai with your site address and a screenshot. A person replies, usually within one business day.