How to track traffic from a GitHub README
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_contentvalues 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 measuremy.site, 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.mdoften links to a code of conduct or issue guide.SECURITY.mdmay 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_contentlink 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.
See it on your own site
measuremy.site is cookieless analytics your coding agent can read. 30-day free trial, no card. Plans from $9/month.
Start free trial See the live demoAdd measuremy.site analytics to this project: connect the measuremy.site MCP server at https://a.measuremy.site/mcp for all my projects (claude mcp add --scope user; it signs in with OAuth, no key, and one sign-in covers every site), then tell me how to sign in. Details: measuremy.site/llms.txt
Free tools
- Visitor counter by country: An embeddable counter of visitors by country.
- Website traffic checker: A site's popularity rank and estimated monthly visits.
- Analytics tag checker: Which analytics and pixels a site runs, plus duplicate and broken tags.
More from the blog
- How to calculate your website conversion rate, and what to compare it to
- Is my A/B test result significant? A plain-English guide with a worked example
- What is bounce rate, how is it calculated, and is yours a problem?
- How to add a visitor counter to your website or GitHub README
- How much traffic does a website get? How to estimate any site's visits
- How to track QR code scans: count them, and see which poster worked
- How to see how many people clicked your link (without a paid shortener)
- How to check if your Google Analytics 4 tag is installed (and only counting once)
- Why GA4 shows your campaign traffic as Unassigned (and how to fix the links)
- Does your redirect keep your UTM tags? How to check before a campaign goes out
- How I built a self-hosted analytics MCP server on Cloudflare Workers and D1
- 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
- Website Data Analytics for Owners: A Practical Guide
- Vanity Metrics vs Useful Metrics: What to Track
- How to Compare Cookieless Website Tracking Tools
- Why Your Analytics Numbers Differ Between Tools
- When GA4 Is Too Much for a Small Website
- How to keep historical data when switching analytics tools
- How to give an AI agent read-only access to your analytics
- Why developers are connecting agents to production data
- How to recover from a sudden traffic drop
- Website analytics for indie hackers: what to watch and what to ignore
- Direct Traffic Explained: Why So Much Is Unknown
- Why a high bounce rate is not always bad
- High bounce rate: 8 causes and practical fixes
- How to Set Up Traffic Alerts for Sudden Drops
- How to Track Traffic From a Podcast
- How to measure the return on a paid ad campaign
- How to use analytics to decide what to write next
- How the Model Context Protocol Works
- Track File Downloads Without Guesswork
- Adding analytics to a Next.js app without slowing it down
- Core Web Vitals and Traffic: Is There a Link?
- Analytics After Cookies: What Actually Changes
- GDPR and website analytics: a practical guide for small sites
- How to Compare Website Analytics Tools by Privacy
- GA4 Events Explained for Beginners
- How to measure a newsletter send with UTM links
- How to track Hacker News traffic
- Adding Analytics to a Framer Site
- How to ask your coding agent about your analytics
- What Is Bounce Rate and How Is It Calculated?
- A practical website analytics retention policy
- Map your site's funnel from first visit to signup
- What Is a Good Bounce Rate?
- How to automate a weekly traffic report
- A Practical Privacy-Friendly Analytics Checklist
- Adding an MCP server to Claude Code
- How long should you keep analytics data?
- How to Build a Small MCP Server That Actually Helps
- How to Find the Biggest Drop Off in a Funnel
- What Is the Urchin Tracking Module?
- What Microsoft MCP servers actually do
- UTM parameters for email newsletters
- Track Button Clicks Without Google Tag Manager
- How to track the results of a social media post without cookies
- How to measure a product launch without guessing