5 ways to watch your GitHub topic to see what's new in the community

I mentioned last week that your community can curate your product's GitHub topic. I also made a side comment that you could watch it to spotlight new community projects.

However, watching topics is not as easy as it sounds. I'll go over 5 ways you can do it today but I'm also working on a small tool called the GitHub Topic Watcher that will do this for you using a more dedicated interface which I'll post separately.

Stay tuned for that!

Starring a topic and getting email updates

The first way that GitHub provides out-of-the-box is by "starring" topics:

Once you star a topic, it will show up in your "Explore" feed:

But as you can see, it is more like a news feed – it's not surfacing repos per topic in a managed way. However, if you are not an individual contributor on GitHub or if you have a work-related GitHub account, starring the topics related to your product and ecosystem could be "good enough" to keep tabs on what's new through the Explore interface.

The next step is to sign up for Email Updates if you want this information sent to you on a regular basis. GitHub has a button in the top right of the explore interface:

And from there you can choose what cadence you want. Similar to the feed, you will get a mix of updates.

This is probably the easiest way to get a bead on what's going on around GitHub but it's not very targeted. For example, if you want to know what's new right away so you can promote it or reach out to the community right away, I don't feel like this method is good enough.

That brings us to the more targeted methods like advanced search, GitHub CLI, and the API.

Using Advanced Search

This is an accessible way anyone can use to track specific topics – but it's manual and you'll need to bookmark it or check back on a cadence.

Using GitHub search, you can enter a search like this:

topic:TOPIC

So for example, this is what you'll see with the following:

topic:awesome-list

You can then use the Sort by dropdown to sort repos by whatever criteria you'd like. Unfortunately, you can't sort by created date, only last updated.

Here are some other criteria you could use:

• stars:>0 – exclude repos without stars
• created:>2023-01-01 – only repos created after a certain date
• topic:TOPIC1 topic:TOPIC2 – include more than one topic (up to 5 total I think!)

This search method works pretty well and is likely the way to go if you don't want to dive into more developer-focused approaches like... the CLI.

Using the GitHub CLI

Like the command line? Then perhaps the GitHub CLI will feel more at home.

GitHub CLI

Take GitHub to the command line

GitHub CLI

To search, you can use the gh search repos command:

$ gh search repos --topic awesome-list --stars ">0" --limit 100 --sort stars

This search finds 100 repos tagged with awesome-list, filters out no-star repos, and sorts by most stars.

You'll get a flat list back, like this:

You can even use the --json flag to output JSON (check out the docs for more!).

The GitHub CLI is a handy way to perform a GH search that leverages the API under the covers if you aren't comfortable writing queries yourself!

But if you are a developer then the last two methods will probably be your cup of tea. ☕

Using the GitHub API

The most advanced way to track topics would be to leverage the GitHub API. There are two ways to use the API and each has an advantage.

The REST API

The most approachable way is using the GitHub REST API. It does not require authorization which means you can use it easily in scripts or without dealing with bearer tokens and headers and all that junk.

Search - GitHub Docs

Use the REST API to search for specific items on GitHub.

GitHub Docs

Here's the URL format you can use:

https://api.github.com/search/repositories?q=topic:TOPIC&sort=updated&p=1&per_page=100

This will return up to 100 repos per page of results and includes a ton of data.

The REST API is "good enough" for most scripting scenarios and it's what I'm using to build my own little tool to watch topics.

The GraphQL API

The most advanced way would be to use the GraphQL API. It actually uses the same kind of search method but you have more customization and ability to batch queries. This requires OAuth and bearer tokens to work but if you're willing to go through that, this is definitely the most flexible and customizable way.

Explorer - GitHub Docs

Get started, troubleshoot, and make the most of GitHub. Documentation for new users, developers, administrators, and all of GitHub’s products.

GitHub Docs

You can play with it using the GitHub GraphQL playground but here's a query that fetches repositories for a topic:

query { 
  search(query: "topic:awesome-list created:>2023-01-01", first: 10, type: REPOSITORY) {
     edges {
      node {
        __typename
        ...repo
      }
    }
  }
}

fragment repo on Repository {
  nameWithOwner
}

You'll get results on the right side and under the fragment, you can add more fields to fetch if you want!

Five ways "should" be enough ways to keep tabs on your community but when I think about the workflow I'd want as a community manager, I'd like to know which repos we've reviewed as a team and have a more dedicated dashboard-like experience. That's where the GitHub Topic Watcher will come in – more on that soon.

Have a lovely day,
Kamran