How to promote your GitHub repo or open-source project

Promoting a GitHub repo is mostly unglamorous: a better first screen, a few well-chosen posts, and the patience to keep showing up after launch day. This is the sequence we recommend to maintainers, whether the project is a weekend CLI or the open-source core of a company.

1. Make the repo worth landing on

Every promotion channel ends at your repo page. If that page doesn’t explain itself in ten seconds, promotion just sends people away faster. Before posting anywhere, check the basics:

• A one-line description that says what the project does.
• A README that opens with a one-paragraph pitch, then a demo, then a one-line install.
• A license, 5 to 10 topics, and the website field filled in if there is a docs site or demo.
• A social preview image, so shared links render as a card.

The details are in README best practices.

2. Write your pitch once, then reuse it

Two sentences: what it does and who it is for. Then a third that says why it beats the obvious alternative. You will paste a version of this into every post, comment and submission form, so write it five ways and keep the clearest.

3. Launch in one concentrated push

Pick a day and do the loud channels on it: Show HN, your social accounts, and the one or two communities where your users live. Concentration matters because GitHub Trending appears to rank recent star velocity, and one good day can put you on it. See how GitHub Trending works, and the launch-day order in how to launch an open-source project.

4. Go where your users already are

Developers rarely browse for new tools in general. They look when they have a specific problem in a specific stack, so the best places to promote a repo are organized around that stack:

• The subreddit for your language or framework, not just r/programming.
• The official Discord, Slack or forum of the framework you build on, in the channel they set aside for showcases.
• Issues and discussions on adjacent projects, only where your project genuinely answers the question being asked, and with your affiliation stated.
• Stack Overflow answers, under the same rule: answer the question first, mention your project second, and say that it is yours.

5. Get listed where your ecosystem looks

Package registries and marketplaces are search engines with high intent. Fill in keywords in package.json, classifiers on PyPI, keywords and categories in Cargo.toml, and list the project in the VS Code Marketplace, Homebrew, or the plugin directory of whatever tool it extends. These listings are slow to pay off and never stop paying.

6. Write about the problem, not the project

A post titled "How we cut cold starts by 80%" gets read by people who have never heard of you. A post titled "Announcing X v1.0" gets read by people who already starred it. Write the first kind, link the repo at the end, and publish it somewhere it can be indexed: your own blog, Dev.to or Hashnode.

7. Submit to lists that last

Awesome lists, newsletters, comparison sites like AlternativeTo, and persistent boards keep sending visitors long after launch traffic is gone. Where to share your GitHub project lists each venue and what it is good for.

8. Turn releases into reasons to post

A release is news. Publish it as a GitHub Release so people watching the repo hear about it, write the changelog in plain language, and post the interesting ones back to the communities you launched in. Several well-spaced updates usually beat one big launch.

9. Measure what promotion actually did

Under Insights, then Traffic, GitHub shows views, unique visitors, clones, top referring sites and most-visited pages for the last 14 days. Check it after every post to see which channels send people. Only people with push access can see it, and it only goes back two weeks, so note the numbers down if you want a longer record.

What not to do

• Buy or trade stars. It breaks GitHub’s rules and barely works. Details in how to get more GitHub stars.
• Paste the same post into twenty subreddits. Mods remove it and the account gets flagged as spam.
• Open pull requests that only add your project to other projects’ READMEs. Awesome lists invite submissions. A stranger’s README does not.

Keep it visible after launch week

Most promotion is a spike. The work that compounds is whatever keeps the repo findable in month three: indexed posts, registry listings, lists, and a board that doesn’t reset overnight. On RepoRanker, listing is free, and $3 buys a place near the top that holds until someone spends more, with the price shown on the row.

List your repo for free.

Related: How to get more GitHub stars · How to market open-source software · Where to share your GitHub project.