GitHub: Create your own repository landscape ⭐️
Tags: github, opensource, githubactions, tooling
Published: 2024-04-28 03:20:25

## Overview 👋

Do you want to create a **central repository** to showcase all your highlighted repositories with descriptions and stars? Something like this:
![example.3.repo](https://github.com/tungbq/repos/blob/main/assets/example.3.repo.png?raw=true)

I've created the repository landscape template [**tungbq/repos**](https://github.com/tungbq/repos) that can help you build your own repository landscape.
This blog post will describe the features and guide you on how to use this repository template to create your own repository landscape.

## Key Features 🚀

The [**tungbq/repos**](https://github.com/tungbq/repos) repository template provides some features that help you create your repo landscape content automatically:

- Supports defining the list of repositories to be shown in the landscape, file `repository_list.txt`.
- Automated script to generate content from the `repository_list.txt`.
- A GitHub Action CI pipeline to generate new repository landscape content:
  - Triggers the automated generation script.
  - Creates a pull request to propose the new content.
- The repository landscape format provides:
  - Indexing with repo name title
  - Repo URL
  - Repo description (archived via GitHub API call)
  - A GitHub stars badge (leverage this tool https://shields.io/)

## Quick start 📖

This is optional; you can skip this section and jump into `Configure and use the template 📘` to create your own repo.
If you want to generate the content locally, update the `repository_list.txt` and run this script:

```bash
git clone https://github.com/tungbq/repos.git
cd repos
./generate_content.sh repository_list.txt
```

Result will be similar to:

```bash
➜  repos git:(main) ✗ ./generate_content.sh repository_list.txt
Working on repo: tungbq/devops-basics, with index: 1
Working on repo: tungbq/AWSHub, with index: 2
Working on repo: tungbq/devops-toolkit, with index: 3
Working on repo: tungbq/devops-project, with index: 4
Working on repo: tungbq/aws-lab-with-terraform, with index: 5
Working on repo: tungbq/awesome-workflow, with index: 6
Working on repo: tungbq/k8sHub, with index: 7
Working on repo: tungbq/Azure-DevOps-Pipeline, with index: 8
Working on repo: tungbq/find-github-issue, with index: 9
Working on repo: tungbq/challenges, with index: 10
Working on repo: tungbq/devops-dockerfiles, with index: 11
Working on repo: tungbq/terraform-sample-project, with index: 12
Working on repo: tungbq/repos, with index: 13
```

Now check the README.md and you would find your repository landscape content

## Configure and use the template 📘
Below are the steps to help you create and configure your own landscape repository.
In short we only need to do 4 major steps: `Create new repo from template` > `Set up GITHUB_TOKEN` > `Update repository list` > `Merge the automated PR`.
Let's dive into the detailed as below:

### 1. Create a new repo from the template

- Visit the template repository: [https://github.com/tungbq/repos](https://github.com/tungbq/repos).
- In the top right corner, select `Use this template` > `Create a new repository`:

  ![create-repo-from-template](https://github.com/tungbq/repos/blob/main/assets/create-repo-from-template.png?raw=true)

- Input your repository name to create and add a description if needed, then select `Create repository`.

  ![create-repo](https://github.com/tungbq/repos/blob/main/assets/create-repo.png?raw=true)

- Wait for a few seconds, and your repository will be created.

### 2. Configure `GITHUB_TOKEN` for the new repo

There is a CI workflow to automatically generate content and open a new Pull Request for your repository landscape, so setting up `GITHUB_TOKEN` permission is required.
<br>
Goto: https://github.com/YOUR_USERNAME/YOUR_REPO/settings/actions (Repo > Setting > Action > General), in the `Workflow permission` section, enable following options:

- Read and write permissions
- Allow GitHub Actions to create and approve pull requests

  ![gh-token-in-repo](https://github.com/tungbq/repos/blob/main/assets/gh-token-in-repo.png?raw=true)

Now we are ready to trigger the CI workflow to update the repo landscape.
Now we are ready to trigger the CI workflow to update the repo landscape.

### 3. Update your repository list

- Add your repository list to the file `repository_list.txt` in your repository and merge it into the `main` branch, for example:

```
tungbq/devops-basics
tungbq/AWSHub
tungbq/devops-toolkit
tungbq/devops-project
tungbq/aws-lab-with-terraform
tungbq/awesome-workflow
```

### 4. Trigger the CI pipeline

#### Automatically trigger on merge event to main

- Once the `repository_list.txt` is merged into the `main` branch, the CI pipeline Update content will be triggered automatically.

  ![ci-main-trigger](https://github.com/tungbq/repos/blob/main/assets/ci-main-trigger.png?raw=true)

- The CI pipeline will read the repository list and generate your new `README.md` content.
- Then, it will check and create a Pull Request to propose the new repository landscape content.

  ![pr-automated](https://github.com/tungbq/repos/blob/main/assets/pr-automated.png?raw=true)

#### Manual trigger (Optional)

- You can also trigger that CI at any moment you want.
- Go to Actions and select Update content.
- Select "Run workflow" to trigger the CI:

  ![action-run](https://github.com/tungbq/repos/blob/main/assets/action-run.png?raw=true)

### 5. Review and merge the PR

Once the PR is raised automatically, you just need to review and merge, and that's it! You will have your own landscape content in README.md.

![pr-merge](https://github.com/tungbq/repos/blob/main/assets/pr-merge.png?raw=true)

Congratulations 🎉, you've successfully created your own repo landscape! Now check the `README.md` for the final result.

## Advance CI configuration (Optional)

- In the previous section, we triggered the CI pipeline to run on a merge event to `main` branch or manual event. You could improve that by changing the trigger event to run on a timer basis. For example, once a week or once a month. This would help us regularly check and update the landscape, keeping it up to date.
- To do so, add your desired cron trigger to `repos/.github/workflows/generate_content.yaml`

```yaml
on:
  schedule:
    - cron: '0 0 * * 6' # Run every Saturday at midnight
  workflow_dispatch:
  # other events as needed
```

- Check https://crontab.guru/ for the CRON syntax

---------------------------------------------------------------
If you find this repository template helpful, feel free to use it, kindly consider showing your appreciation by giving it a star ⭐️. Any star you can give me will help me grow it even more ❤️

<table>
	<tr>
		<td>
			<a href="https://github.com/tungbq/repos" style="text-decoration: none;"><strong>Star repos ⭐️ on GitHub</strong></a>
		</td>
	</tr>
</table>
Thank you and happy coding! 🔥