Overview π
Do you want to create a central repository to showcase all your highlighted repositories with descriptions and stars? Something like this:
I've created the repository landscape template 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 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:
git clone https://github.com/tungbq/repos.git
cd repos
./generate_content.sh repository_list.txt
Result will be similar to:
β 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.
- In the top right corner, select
Use this template
>Create a new repository
:
- Input your repository name to create and add a description if needed, then select
Create repository
.
- 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.
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
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 themain
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 themain
branch, the CI pipeline Update content will be triggered automatically.
- 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.
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:
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.
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
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 β€οΈ
Thank you and happy coding! π₯
Top comments (17)
You don't actually need a PAT to create a PR from a GitHub Actions workflow. The
GITHUB_TOKEN
is sufficient for PRs, with the right permissions.Actually, it depends on your setup. Most repositories won't need a PAT and can use the default token generation. However if your repository has branch protection rules for the target branch and there's some CI, this won't work. Workflows can't trigger workflows is a basic rule in GHA. This means that if GITHUB_TOKEN opens a PR, the CI won't run on it. There are several workarounds: the simplest is to have the CI on pull_request: trigger and close+reopen the PR, because it's a human doing it, the CI will run. Another option is setting up a PAT so that the automated PR creation is "done by a human". In this case GHA can't distinguish between the workflow creating the PR or you manually, so CI will run as usual.
Thanks for your feedback, that's very useful for the understanding of the term "done by human" and the GitHub token permission point of view. I'll review this to see if I could make more improvements to my repository
Thanks for confirming what I thought
You're welcome
Yes, Thank you for suggesting this point @cicirello.
I will try to use the workflow with GITHUB_TOKEN and update the latest document in my repo once itβs working fine.
I updated this one in latest release: v0.4.0.
Via this PR github.com/tungbq/repos/pull/30
Thank you again @cicirello and @ccoveille for your feedback and suggestion!
My pleasure
You're welcome
Hi thank you for the tutorial but i am getting this error do u know why it could be or if u could help me with it thanks
Thank you for your feedback @kaushal01 !
I've switched the tooling to use
GITHUB_TOKEN
recently and update document on my repository, but this blog post is missing the new document.It seems that you need to grant the
GITHUB_TOKEN
permission, please enable below option and re-try again.Goto:
https://github.com/YOUR_USERNAME/YOUR_REPO/settings/actions
(Repo > Setting > Action > General), in the Workflow permission section, enable following options:
I've mentioned this configuration in the section #2 in this post as well.
Thank you very much this works
You are welcome!
Interesting project thanks.
Did you build this a part of a personal challenge? Or because you find nothing else to do it?
What were the existing alternative projects you considered ? if they are any
Hi @ccoveille, thanks for your feedback.
Itβs built as part of my personal idea and experience to summarize and track my favorite projects in a central repository.
Iβve searched around but have not found similar project like this yet, so I just build my own and share to everyone who interested.
And yes if you find any similar projects like this please let me know. Thanks!
Following discussion that happened in comments on @_michellemello post
Upgrading your GitHub readme
Michelle Mello γ» Apr 27
I'm curious to know what @best_codes @clintonrocha98 @phalkmin think about @tungbq initiative and if you knew something equivalent or existing alternatives
Great write-up! We also have a bunch of articles on Github Actions in our Newsletter, check it out - packagemain.tech/p/github-actions-...