Is there a way to show case the users that used my github template?

Question

I have created a github repo template, and some users used it.

My question is how to show the people who use my github repo template.

For example in the Used By section. If I can't add it in the Used by section how to embed it in the Read me.

For context I have a friend who generated a repo from my template.

This is the repo for more context: https://github.com/Bashamega/ebookCraft

Answer 1

You'll be able to see/access public forks of your repo in the Forks and Network sections.

If you want to embed this in your README, you'll need to use the GitHub API. This is a pretty similar program that uses GitHub Actions to display contributors in your README. You could fork this action and edit the API calls to fetch from Forks, then use it in a workflow.

Answer 2

To showcase users who have used your GitHub repository template, you might not be able to automatically update the "Used by" section, as this typically refers to GitHub Actions or packages being used by other repositories.

However, you can manually track and display this information in your README file by following these steps:

• Keep track of repositories that have been created from your template. GitHub does not automatically provide a list of repositories created from your template, so you will need to manually monitor this or ask users to inform you when they use your template.

• Once you have a list of users or repositories that have used your template, you can manually update your README file to include a section showcasing these users or their projects.

• Embedding in README:

  • Markdown Table: Create a Markdown table in your README to list the users and links to their generated repositories.
  • Badges: Use badges (for example, from shields.io) to visually represent the number of users or specific users.
  • Links: Simply list the repositories with links to them.

Example Markdown for README:

## Projects Using That Template

We are proud to showcase projects that have been created using our template:

| User       | Repository                                     |
| ---------- | ---------------------------------------------- |
| @username1 | [Repo Name](https://github.com/username1/repo) |
| @username2 | [Repo Name](https://github.com/username2/repo) |

Feel free to [let us know](https://github.com/Bashamega/ebookCraft/issues/new) if you have used this template for your project!

That approach requires manual updates to your README, so it is best suited for situations where the volume of users using the template is manageable.

---

For automation, you could explore GitHub Actions or scripts that periodically search GitHub for repositories mentioning your template in their README or have been forked/cloned from your template. However, this would require significant setup and may not always be accurate.

However, you can employ a creative workaround using the GitHub API and GitHub Actions to approximate this functionality.

• You can search for repositories with a specific topic or description that matches your template repository. Encourage users of your template to include a unique hashtag or keyword in their repository description, or to use a specific topic.
  Ask users of your template to add a unique topic to their repository, such as #BasedOnYourRepoName.

• Automate the process of fetching this information and updating your README.md file.
  Create a GitHub Action in your repository to periodically search for repositories using your template by looking for your unique hashtag or topic.

The GitHub workflow would be:

name: Update Template Users List

on:
  schedule:
    - cron: '0 0 * * *' # Runs every day at midnight
  workflow_dispatch:

jobs:
  update-readme:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      
      - name: Fetch repositories
        id: fetch_repos
        uses: octokit/[email protected]
        with:
          route: GET /search/repositories?q=topic:BasedOnYourRepoName+in:description+fork:true
          mediaType: '{"previews": ["mercy"]}'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Update README
        run: |
          REPO_LIST=$(echo '${{ steps.fetch_repos.outputs.data }}' | jq -r '.items[] | .full_name')
          README_CONTENT="## Repositories Using That Template\n"
          for REPO in $REPO_LIST; do
            README_CONTENT+="- [$REPO](https://github.com/$REPO)\n"
          done
          echo "$README_CONTENT" > README.md
          git config --global user.email "[email protected]"
          git config --global user.name "GitHub Action"
          git commit -am "Update README with template users list"
          git push

That action:

• searches for repositories with the specified topic in their description.
• updates the README.md file with a list of repositories using your template.
• commits and pushes the changes to your repository.

That only works if the users of your template follow your guidelines to include a specific topic or keyword. It is not foolproof but offers a method to showcase template adoption.

Answer 3

A script like the below can be used to find the repos within a limited set of orgs/users, that were generated from a specific repo template. In theory, the script will work for all github repos as well, but in practice, it will take way too long and will run into Github's API rate limits. The script is written in Groovy and uses Github's GraphQL API.

import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import java.net.http.HttpRequest.BodyPublishers
import java.net.http.HttpResponse.BodyHandlers

import groovy.json.JsonOutput
import groovy.json.JsonSlurper

def orgs = [
        'devatherock',
        'cortinico',
]
String templateRepo = 'cortinico/kotlin-gradle-plugin-template'

HttpClient client = HttpClient.newBuilder().build()
String gitToken = System.getenv('GIT_TOKEN')
JsonSlurper jsonSlurper = new JsonSlurper()
def matchedRepos = []

orgs.each { org ->
    def results
    String startAfter = null

    do {
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create('https://api.github.com/graphql'))
                .header('Content-Type', 'application/json')
                .header('Authorization', "Bearer ${gitToken}")
                .POST(BodyPublishers.ofString(JsonOutput.toJson(['query': buildQuery(org, startAfter)])))
                .build()
        HttpResponse response = client.send(request, BodyHandlers.ofString())
        def parsedResponse = jsonSlurper.parseText(response.body())

        results = parsedResponse.data.repositoryOwner.repositories.nodes
        startAfter = parsedResponse.data.repositoryOwner.repositories.pageInfo.endCursor

        results.each { repo ->
            if (repo.templateRepository && repo.templateRepository.nameWithOwner == templateRepo) {
                matchedRepos.add(repo.nameWithOwner)
            }
        }
    } while (startAfter != null)
}
println(JsonOutput.prettyPrint(JsonOutput.toJson(matchedRepos)))

String buildQuery(String org, String startAfter) {
    String query
    String startAfterFilter = ''

    if (startAfter != null) {
        startAfterFilter = """after: "${startAfter}", """
    }

    query = """
        query {
            repositoryOwner(login: "${org}") {
                repositories(${startAfterFilter}first: 100) {
                    nodes {
                        nameWithOwner
                        templateRepository {
                            nameWithOwner
                        }
                    }
                    pageInfo {
                        endCursor
                    }
                }
            }
        }
    """.stripIndent().trim()

    return query
}

With the hardcoded inputs, the script looks for usages of the template cortinico/kotlin-gradle-plugin-template within orgs/users devatherock and cortinico and returns the below output:

[
    "cortinico/ktfmt-gradle",
    "cortinico/reproducer-gradle-classpath-property",
    "cortinico/reproducer-agp-74rc01"
]