Skip to content

Latest commit

 

History

History
82 lines (61 loc) · 4.89 KB

setup.md

File metadata and controls

82 lines (61 loc) · 4.89 KB
Raw

Automatic Repo Organization into a read me based on tagged Topics

Set Up

GitHub Actions configuration

Enabaling the GitHub actions workflow that automatically generates the README.md file for all the repositiories within an organization (both public and private) requires an initial setup at the organizational level in GitHub before private repos will appear in the README.

You'll need an admin/owner for the organization this repo is a part of to follow instructions from GitHub on adding the Read and Write permissions scope for actions for the GitHub actions GITHUB_TOKEN used for authentication. Have the organization admin/owner follow instructions fro GitHub on configuring the default token permissions.

The organizational admin/owner will also need to set up a personal access token owned by the organization and add it to the repository's secrets with the name REPO_FINE_GRAIN_TOKEN for the worklfow to have permissions to read all repos (public and private) owned by the organization. Note that this will grant round-about access to read all repos (both public and private) owned by the organization and which may not be desireable in public repositories or private repositories with collaborators from outside of the organization.

If you only want public repos listed the GITHUB_TOKEN can be specified in place of REPO_FINE_GRAIN_TOKEN in the workflow yaml file and the above step of making a personal access token can be skipped.

Local Development configuration

Local development requires the installation of GitHub CLI and the configuration of it with your GitHub account.

Topic to section mappings

The GitHUb Action organizes the repos based on specific topics. Esentially, if a repo is tagged with one or more specific Topics then it'll appear formatted in the given section of the autogenerated README.

Sections are mapped to topics using the following table:

Section Associated Topic
Software Development software
Project-based Analysis see below for per-project topics
DevOps devops
SciOps sciops
Pipelines pipeline
Support support
Workflow Management workflow
Miscellaneous all other topics not listed above

Per-project Topics: cystic-fibrosis, mecfs, nf1, ptc, pvp, pah, udn

Adding new Per-project Topic

⚠️ Topics on GitHub are public, i.e. anyone could see and use them across all of GitHub, so DO NOT include any collaborator information or private CGDS names or acronyms if you're creating a new Topic to tag your repo with. Topics being public will not cause your repo to become public. When in doubt try using already existing Topics for tagging per-project repos.

Adding a new per-project topic follows these steps:

  1. add the project/disease acronym as a Topic tag to your repo(s)
  2. add a new project subsection under the ## Project-based Analysis heading in the generate README script
  3. copy the whole gh command from another per-project section under your new section and change the XXX in the topic filter option --topic XXX to your topic from step 1
  4. add your topic to the blacklist on the gh command in the ## Miscellaneous section
  5. update the Topic Mappings section of this doc to include the info on your new topic

Generating New README for testing and PRs

Part of the process of using this automatic generation of an updated README is checking that the new changes look good and run. All of the query and formatting logic is contained within the generate README script and this script is run by the GitHub action. To test updates to the script ensure that you've installed and configured the GitHub CLI and then the README can be updated by running the following command from the root directory of the repo

bash .github/generate_readme.sh

You can inspect the README text as well as preview the markdown rendering if using VS Code. Once the changes look satisfactory commit and push the changes to your branch and submit a PR for them to be merged into the main branch.