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, Strapi or Payload. 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. - Leave Let SEOmatic merge its own changes ticked if you want approved page changes to go live without a trip to GitHub. Untick it to merge every pull request yourself.
- 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.
Every change is a pull request first
SEOmatic never commits straight to your main branch. Each change is a pull request on its own branch, which you can read on GitHub. To stop at any time, uninstall the SEOmatic AI app from your repository on GitHub. Open pull requests stay yours.
Who Merges the Pull Request#
With Let SEOmatic merge its own changes on (the default), approving a page change in SEOmatic (a title, a description, structured data, links, alt text) is enough: SEOmatic merges its pull request for you and the card says Approved: merging the pull request on GitHub, then your site deploys it. It does this while your plan or your trial with a card is active and your agents are on.
SEOmatic leaves the merge to you, and the card starts with Merge it on GitHub and says why, when:
- the pull request is a code change (a technical fix or a template), or a draft. Drafts say Let your build run, mark it ready for review, then merge it on GitHub
- it conflicts with newer changes in your repository
- one of your repository's checks failed on it
- your branch protection asks for a review or a check first. Your branch protection always wins
- it was still not ready to merge an hour after it was opened
- your agents are off
To change who merges, open Connections, and in the GitHub section under your connection switch Let SEOmatic merge its own changes on or off.
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 the Merge#
SEOmatic follows your host's deploy, then checks your live page for the exact change. Only when it finds it is the fix marked Merged and live on your site. If you close a pull request without merging, that fix is dismissed.
| The card says | What it means |
|---|---|
| Going live: your host is deploying the merged change | Your host (Vercel, Netlify and so on) is building the site. SEOmatic checks the live page as soon as it finishes. |
| Needs you: your host could not deploy the merged change | The deploy failed. Run it again on your host, and the change goes live by itself. |
| Ready: publish your site | Nothing on GitHub deploys your site, so publish it yourself. On a Lovable project, click Publish changes in Lovable. |
| Merged, but not showing on your site after four days of checks | Check that your site rebuilt after the merge and that it publishes from the branch the pull request went into. Or dismiss the task. |
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 Connections, the GitHub section under your connection adds an SEO check to pull requests. By default it reports only and never blocks a merge.
- 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.


