How to track traffic from a GitHub README

October 5, 2026 · 5 min read

Why GitHub README traffic needs its own tracking

GitHub's repository traffic view gives you a useful signal about how many people visit the repo or clone it. It does not always break out which README link sent someone to your documentation, demo, or product site. If your README is the front door to a project, that gap matters.

The practical way to close it is to add UTM parameters to the outbound links in the README and let your website analytics record the visits.

Start with one campaign per repository

Use utm_source=github and utm_medium=readme for every link from the README to your site. Set utm_campaign to the repository name or a stable project slug. Use utm_content for the specific link.

[Try the demo](https://example.com/demo/?utm_source=github&utm_medium=readme&utm_campaign=my-project&utm_content=demo-link)

Keeping the campaign name stable matters. If you change it with every README edit, your reports become fragmented and harder to compare over time.

If the same repository links to two different products or subdomains, you can still use one campaign and separate them by utm_content or by the landing page. Avoid creating a separate campaign for every link, because that makes it harder to see the repository as a single traffic source.

Tag the links people actually click

A README often contains several links to the same domain. Treat each one as a separate entry point.

• Project title or logo link to the homepage.
• Documentation link.
• Live demo link.
• Getting-started guide link.
• Changelog or release notes link.
• Badge or shield that points to your site.

Use utm_content to separate links that share the same source, medium, and campaign. For example, the hero link at the top and the documentation link in the middle can both use utm_source=github&utm_medium=readme&utm_campaign=my-project, but one has utm_content=hero and the other has utm_content=docs.

Why referrer data is not enough

Some analytics tools show github.com as a referrer even when the link has no UTM parameters. That tells you GitHub sent traffic, but not which link was clicked. With UTM parameters, you can separate the homepage link from the docs link and the demo link. That is the difference between knowing that GitHub sent visitors and knowing what a reader was looking for.

Do not try to run a tracking script in the README

A GitHub README is rendered markdown. It does not execute the script you place on your website, and GitHub README files do not execute arbitrary JavaScript. Measurement happens when the visitor arrives on your site with the UTM parameters in the URL.

This means the destination site must record the visit. If a link goes to a page you do not control, you cannot reliably measure what happens after the click.

What to look for after a few days

Once the tagged links are live, let them collect data for a few days before drawing conclusions.

• Compare utm_content values to see which README links get clicked most often.
• Look at the landing pages for those visits to check that the right page is receiving them.
• See whether README visitors continue to other pages or leave immediately.
• If you track signups or custom events, check whether the GitHub README campaign converts.

In agentlytics, tracked campaign links with UTM tags credit later traffic and signups, so you can follow a README visit through to a signup without setting a cookie. That gives you a clearer view of whether the README is bringing in useful visitors, not just clicks.

Keep the links readable and consistent

Long URLs with many parameters can look messy in a README, but consistency matters more than prettiness.

• Use lowercase campaign names and hyphens instead of spaces.
• Put the campaign name in the same place in every URL.
• Avoid adding parameters that change for no reason.
• If you use a link shortener, make sure it preserves the UTM parameters or adds them on the destination page.

If the README is part of a template used across many repositories, keep a shared convention. For example, source is always github and medium is always readme; only the campaign changes from repo to repo.

Add the same discipline to related markdown files

The README is usually the biggest source of external traffic, but it is not the only markdown file in a repository.

• CONTRIBUTING.md often links to a code of conduct or issue guide.
• SECURITY.md may link to a security policy page.
• Release notes may link to a changelog or migration guide.
• The repository description or website field can also point to your site.

If those links point to your domain, tag them with the same source and medium. You can use a different campaign or content value to distinguish the file.

A simple workflow

• List every outbound link in the README.
• Decide on one campaign name for the repository.
• Add UTM parameters to each link.
• Commit the change and push.
• Wait a few days, then check the campaign report.

If you work with a coding agent, ask it to add UTM parameters to every README link that points to your domain. That is a good task to put in a project rule or a pull request checklist.

Use the data to improve the README

After a few weeks, you can use the results to change the README itself.

• If the demo link gets far more clicks than the documentation link, make the demo easier to find.
• If a particular utm_content link sends traffic that converts, move that link higher.
• If a link gets almost no clicks, remove it or change its label.
• If README visitors rarely go past the landing page, the page they land on may not match the README's promise.

Tracking README traffic is not just about counting clicks. It helps you understand what a developer expects after reading the project description and whether your site delivers on that expectation.

A GitHub README can be a steady source of qualified visitors, but only if you tag the links and read the campaign reports. Start with a clear UTM scheme, keep it stable, and let the data guide small changes to the README and the pages it links to.

More from the blog

• UTM tracking explained: what the parameters mean and how to use them
• Conversion funnel analysis for small sites: a practical guide
• Sudden drop in website traffic? A checklist for finding the cause
• What is an MCP server? A plain-English guide for people who run websites
• How to measure a product launch without guessing