Skip to content

Commit 4fcc224

Browse files
hdamkerhdamker
authored
Update of automation workflow setup-new-repo, templates and documentation (#21)
* Update README.md * Update README.md * Update initial-admin.md * Update setup-new-repo.yml adding cleanup step * Update setup-new-repo.yml * Update setup-new-repo.yml * Update setup-new-repo.yml * Update setup-new-repo.yml * Update setup-new-repo.yml * Update setup-new-repo.yml * Update setup-new-repo.yml * Update setup-new-repo.yml * Update setup-new-repo.yml * Refactored clean up step * Update prerrequisites * Renamed CODEOWNERS_TEMPLATE * More detailed repository description * Added comments within the workflow * Updated workflow documentation * Some more comments and improvements of the workflow * Revert change of token check * Update documentation regarding token creation
1 parent 07dc082 commit 4fcc224

6 files changed

Lines changed: 191 additions & 96 deletions

File tree

‎.github/workflows/setup-new-repo.yml‎

Lines changed: 74 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,18 @@
11
# .github/workflows/setup-new-repo.yml
2+
#
3+
# Prerequisites:
4+
# - A GitHub environment named `repo-setup` must exist.
5+
# - The environment must contain a secret `GH_REPO_CREATE_TOKEN`.
6+
# - This token must be a fine-grained personal access token (FGPAT) with the following:
7+
# • Repository access: Allow access to the template repo and target org repos.
8+
# • Permissions:
9+
# - Contents: Read and write
10+
# - Issues: Read and write
11+
# - Metadata: Read-only
12+
# - Administration: Read and write (for repo settings, team setup)
13+
#
14+
# See: https://github.com/settings/tokens for generating tokens
15+
#
216
name: Setup New Repository
317

418
on:
@@ -38,24 +52,39 @@ jobs:
3852
- name: Checkout template repository
3953
uses: actions/checkout@v4
4054

41-
- name: Set up GitHub CLI token with personal access token
55+
- name: Set up GitHub CLI token with personal fine grained access token
4256
run: |
57+
# Use GH_REPO_CREATE_TOKEN as the authentication token for all GitHub CLI commands
4358
echo "GH_TOKEN=${{ secrets.GH_REPO_CREATE_TOKEN }}" >> $GITHUB_ENV
44-
echo "Token GH_REPO_CREATE_TOKEN ready for use in GitHub CLI"
59+
if [ -z "${{ secrets.GH_REPO_CREATE_TOKEN }}" ]; then
60+
echo "::error::GH_REPO_CREATE_TOKEN is not set. Please configure the secret in the 'repo-setup' environment."
61+
exit 1
62+
fi
4563
4664
- name: Create new repository and set variables
4765
run: |
4866
REPO_NAME=${{ github.event.inputs.repo_name }}
67+
# Extract the owner (user or organization) part of the current repository (before the slash)
4968
OWNER=$(echo '${{ github.repository }}' | cut -d'/' -f1)
5069
51-
echo "Checking if repository $OWNER/$REPO_NAME already exists..."
52-
if gh api repos/$OWNER/$REPO_NAME > /dev/null 2>&1; then
53-
echo "::error::Repository $OWNER/$REPO_NAME already exists. Exiting."
54-
exit 1
55-
fi
56-
5770
echo "Creating new repository: https://github.com/$OWNER/$REPO_NAME"
58-
gh repo create "$OWNER/$REPO_NAME" --public --template "$OWNER/$(basename '${{ github.repository }}')" --confirm
71+
# Creates a new public repository using the current repository as a template
72+
gh repo create "$OWNER/$REPO_NAME" --public --template "$OWNER/$(basename '${{ github.repository }}')"
73+
74+
# Wait until the repository is fully accessible
75+
for i in {1..5}; do
76+
if gh api repos/$OWNER/$REPO_NAME > /dev/null 2>&1; then
77+
echo "::notice::Repository $OWNER/$REPO_NAME is now available."
78+
break
79+
else
80+
echo "Waiting for repository $OWNER/$REPO_NAME to become available..."
81+
sleep 4
82+
fi
83+
done
84+
85+
if ! gh api repos/$OWNER/$REPO_NAME > /dev/null 2>&1; then
86+
echo "::warning::Repository $OWNER/$REPO_NAME did not become available after 5 attempts. Continuing anyway."
87+
fi
5988
6089
echo "REPO_NAME=$REPO_NAME" >> $GITHUB_ENV
6190
echo "OWNER=$OWNER" >> $GITHUB_ENV
@@ -67,6 +96,7 @@ jobs:
6796
run: |
6897
if gh api orgs/$OWNER/teams > /dev/null 2>&1; then
6998
if ! gh api orgs/$OWNER/teams/$MAINTAINERS_TEAM > /dev/null 2>&1; then
99+
# Retrieve the numeric ID of the 'maintainers' team to use as the parent_team_id
70100
MAINTAINERS_PARENT_ID=$(gh api orgs/$OWNER/teams/maintainers | jq -r '.id')
71101
MAINTAINERS_PARENT_ID_NUM=$(echo "$MAINTAINERS_PARENT_ID" | grep -o '[0-9]*')
72102
echo "Debug: MAINTAINERS_PARENT_ID_NUM=$MAINTAINERS_PARENT_ID_NUM"
@@ -101,6 +131,10 @@ jobs:
101131
fi
102132
103133
CODEOWNERS_LIST=$(echo "$CODEOWNERS_LIST" | xargs)
134+
# Loop through each provided GitHub username and invite them to the codeowners team
135+
# Note: users who are not yet members of the organization will be invited to join
136+
# and will need to accept the invitation before they are part of the team and the CODEOWNERS file get fully valid
137+
echo "Inviting users to team $CODEOWNERS_TEAM: [$CODEOWNERS_LIST]"
104138
for username in $CODEOWNERS_LIST; do
105139
clean_user=$(echo "$username" | sed 's/^@//')
106140
echo "Checking if @$clean_user is a valid GitHub user..."
@@ -118,7 +152,7 @@ jobs:
118152
- name: Configure repository settings
119153
run: |
120154
gh repo edit $OWNER/$REPO_NAME \
121-
--description "$REPO_NAME" \
155+
--description "Sandbox API Repository for $REPO_NAME API(s)" \
122156
--homepage "${{ github.event.inputs.repo_wiki_page }}" \
123157
--add-topic sandbox-api-repository
124158
gh api -X PATCH repos/$OWNER/$REPO_NAME \
@@ -128,14 +162,16 @@ jobs:
128162
129163
- name: Update README.md placeholders
130164
run: |
131-
# changes the README.md from template repository and updates the README.md in the new repository with it
165+
# Replace placeholders in the template README.md and push the updated version to the new repository
166+
# Note: the README.md file is expected to be in the root of the repository
132167
sed -i "s/{{repo_name}}/$REPO_NAME/g" README.md
133168
sed -i "s|{{repo_wiki_page}}|${{ github.event.inputs.repo_wiki_page }}|g" README.md
134169
sed -i "s|{{subproject_name}}|${{ github.event.inputs.subproject_name }}|g" README.md
135170
sed -i "s|{{subproject_wiki_page}}|${{ github.event.inputs.subproject_wiki_page }}|g" README.md
136171
sed -i "s|{{mailinglist_name}}|${{ github.event.inputs.mailinglist_name }}|g" README.md
137172
sed -i "s|{{initial_codeowners}}|${{ github.event.inputs.initial_codeowners }}|g" README.md
138173
174+
# Retry loop: waits for README.md to appear in the new repo (max 5 attempts)
139175
SHA=""
140176
for i in {1..5}; do
141177
SHA=$(gh api repos/$OWNER/$REPO_NAME/contents/README.md 2>/dev/null | jq -r '.sha')
@@ -185,7 +221,10 @@ jobs:
185221
186222
- name: Update CODEOWNERS file
187223
run: |
188-
sed "s|{{initial_codeowners}}|$CODEOWNERS_LIST|g" templates/CODEOWNERS > CODEOWNERS
224+
# Replace placeholder in CODEOWNERS template with actual list of codeowners
225+
# Note: also users who are skipped during team invitation will be added to the CODEOWNERS file and
226+
# might need to be corrected manually later and invited manually to the CODEOWNERS team
227+
sed "s|{{initial_codeowners}}|$CODEOWNERS_LIST|g" templates/CODEOWNERS_TEMPLATE > CODEOWNERS
189228
CODEOWNERS_SHA=$(gh api repos/$OWNER/$REPO_NAME/contents/CODEOWNERS | jq -r '.sha')
190229
191230
gh api repos/$OWNER/$REPO_NAME/contents/CODEOWNERS \
@@ -200,6 +239,7 @@ jobs:
200239
TEMPLATE_REPO=$(basename "${{ github.repository }}")
201240
echo "Fetching rulesets from $OWNER/$TEMPLATE_REPO"
202241
242+
# Fetch all rulesets defined in the template repository for later replication
203243
RULESETS=$(gh api repos/$OWNER/$TEMPLATE_REPO/rulesets \
204244
-H "Accept: application/vnd.github+json" 2>/dev/null || echo "[]")
205245
@@ -236,3 +276,25 @@ jobs:
236276
gh issue comment "$ADMIN_ISSUE_URL" \
237277
--body "✅ Repository setup has been completed by automation. You may now proceed with the checklist."
238278
279+
- name: Cleanup setup artifacts from template repository
280+
run: |
281+
# Explicit list of files to remove after setup (e.g., templates and placeholders)
282+
FILES_TO_DELETE=(
283+
"templates/CODEOWNERS"
284+
"templates/issues/initial-admin.md"
285+
"templates/issues/initial-codeowners.md"
286+
"templates/README.md"
287+
)
288+
289+
for file in "${FILES_TO_DELETE[@]}"; do
290+
if gh api repos/$OWNER/$REPO_NAME/contents/$file > /dev/null 2>&1; then
291+
sha=$(gh api repos/$OWNER/$REPO_NAME/contents/$file | jq -r '.sha')
292+
gh api repos/$OWNER/$REPO_NAME/contents/$file \
293+
-X DELETE \
294+
-F message="Remove $file from template repository" \
295+
-F sha="$sha" || echo "::error::Failed to delete $file"
296+
echo "::notice::Deleted $file"
297+
else
298+
echo "::warning::File $file not found during cleanup. Skipping."
299+
fi
300+
done

‎CODEOWNERS‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# This file provides an overview of code owners in this repository.
1+
# This file provides an overview of code owners in this repository
2+
3+
# Note: this is the actual CODEOWNERS file to protect the template repository. The CODEONWERS file in newly created repositories will be build based on /templates/CODEOWNERS_TEMPLATE
24

35
# Each line is a file pattern followed by one or more owners.
46
# The last matching pattern has the most precedence.

‎README.md‎

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,42 +5,45 @@
55
<a href="https://github.com/camaraproject/{{repo_name}}" title="Repo Size"><img src="https://img.shields.io/github/repo-size/camaraproject/{{repo_name}}?style=plastic"></a>
66
<a href="https://github.com/camaraproject/{{repo_name}}/blob/main/LICENSE" title="License"><img src="https://img.shields.io/badge/License-Apache%202.0-green.svg?style=plastic"></a>
77
<a href="https://github.com/camaraproject/{{repo_name}}/releases/latest" title="Latest Release"><img src="https://img.shields.io/github/release/camaraproject/{{repo_name}}?style=plastic"></a>
8-
<!-- Choose one of the following alternatives and then delete the task -->
98
<a href="https://github.com/camaraproject/Governance/blob/main/ProjectStructureAndRoles.md" title="Sandbox API Repository"><img src="https://img.shields.io/badge/Sandbox%20API%20Repository-yellow?style=plastic"></a>
109
<a href="https://github.com/camaraproject/Governance/blob/main/ProjectStructureAndRoles.md" title="Incubating API Repository"><img src="https://img.shields.io/badge/Incubating%20API%20Repository-green?style=plastic"></a>
1110
<a href="https://github.com/camaraproject/Governance/blob/main/ProjectStructureAndRoles.md" title="Graduated API Repository"><img src="https://img.shields.io/badge/Graduated%20API%20Repository-silver?style=plastic"></a>
1211
<a href="https://github.com/camaraproject/Governance/blob/main/ProjectStructureAndRoles.md" title="Working Group"><img src="https://img.shields.io/badge/Working%20Group-red?style=plastic"></a>
12+
<!-- Choose one of the above four alternative badges and then delete this task -->
1313

1414
# {{repo_name}}
1515

1616
> [!NOTE]
17-
> What is this repository about and how to use it:
17+
> What is this template repository about and how to use it:
1818
>
19-
> * For codeowners of existing CAMARA repository as a sample how a CAMARA repository should look like, e.g. to update legacy repositories. Have a look specifically on the [code of the README.md](https://github.com/camaraproject/Template_API_Repository/blob/main/README.md?plain=1) for different variants and copy relevant parts into your repository.
19+
> * For codeowners of existing CAMARA repository it is a sample how a CAMARA repository should look like, e.g. to update legacy repositories. Have a look specifically on the [code of the README.md](https://github.com/camaraproject/Template_API_Repository/blob/main/README.md?plain=1) for different variants and copy relevant parts into your repository.
2020
> * For CAMARA admins to create new (Sandbox) API repositories automated: Use the `setup-new-repo` workflow together with documentation in [templates/README.md](templates/README.md).
2121
>
22-
> The following is the template README for a new independent Sandbox API repository, other variants are within the commented code.
22+
> The following is the template README for a new independent Sandbox repositories, Sandbox repositories within a Sub Project, and Incubated Repositories. Further variants are within the commented code.
23+
>
24+
> This note must be deleted in newly created repositories
25+
26+
---
27+
<!-- Choose one of the following alternatives and then delete this task -->
2328

24-
<!-- Alternative for new, independent Sandbox API Repositories -->
29+
<!-- Alternative for new, independent Sandbox API Repositories. Choose the "Sandbox" badge above -->
2530
Sandbox API Repository to describe, develop, document, and test the {{repo_name}} Service API(s). The repository does not yet belong to a CAMARA Sub Project.
2631

2732
* API Repository [wiki page]({{repo_wiki_page}})
2833

29-
<!-- Alternative for Sandbox API Repositories within the context of an existing Sub Project -->
34+
---
35+
<!-- Alternative for Sandbox API Repositories within the context of an existing Sub Project. Choose the "Sandbox" badge above -->
3036

31-
<!--
3237
Sandbox API Repository to describe, develop, document, and test the {{repo_name}} Service API(s) within the Sub Project [{{subproject_name}}]({{subproject_wiki_page}})
3338

3439
* API Repository [wiki page]({{repo_wiki_page}})
35-
-->
3640

37-
<!-- Alternative for Incubating API Repositories (always part of Sub Project, potentially created as part of the Incubation) -->
41+
---
42+
<!-- Alternative for Incubating API Repositories (always part of Sub Project, potentially created as part of the Incubation). Choose the "Incubating" badge. Change the repository topic to "incubating-api-repository" -->
3843

39-
<!--
4044
Incubating API Repository to evolve and maintain the definitions and documentation of {{repo_name}} Service API(s) within the Sub Project [{{subproject_name}}]({{subproject_wiki_page}})
4145

4246
* API Repository [wiki page]({{repo_wiki_page}})
43-
-->
4447

4548
<!-- for Graduation of an API Repository replace "Incubating" with "Graduated" and don't forget to exchange the badge :-) -->
4649

@@ -49,7 +52,7 @@ Incubating API Repository to evolve and maintain the definitions and documentati
4952
Repository for xxx of the {{subproject_name}} Working Group"
5053
5154
* Working Group [wiki home page]({{repo_wiki_page}})
52-
!! Update with concrete link
55+
5356
-->
5457

5558
## Scope

templates/CODEOWNERS renamed to templates/CODEOWNERS_TEMPLATE

File renamed without changes.

0 commit comments

Comments
 (0)