Kürzlich habe ich festgestellt, dass ich eine CODEOWNERS-Datei in mehrere Repositories innerhalb unserer Github-Organisation einbinden musste. Das Ziel bestand darin, automatisch Reviewer für Pull Requests festzulegen. Codeowner sind dafür das perfekte Tool. Auf diese Weise kann jeder Mitarbeitende im Unternehmen unserer GitHub-Organisation beitreten und Schreibzugriff auf die Repositories erhalten (damit sie Branches erstellen können) und schließlich Pull Requests erstellen, ohne sie in ihre persönlichen Konten kopieren zu müssen.
Ich wollte jedoch unbedingt vermeiden, die Codeowners-Datei auf folgende Weise zu erstellen:
- Alle Repositories klonen, Dateien hinzufügen, committen und pushen (am besten über einen Pull Request)
- Die Dateien über die GitHub-Benutzeroberfläche hinzufügen (d.h. auf “Datei hinzufügen” klicken, “Neue Datei erstellen”, Inhalt einfügen und committen).
Glücklicherweise kann man dies auch über die REST-API von GitHub automatisieren. Es war jedoch schwieriger als erwartet!
Ich wollte keine einzelnen Personen zur Codeowners-Datei hinzufügen, da ich die Datei ändern müsste, wenn eine Person das Unternehmen verlässt oder nicht mehr als Codeowner fungieren möchte. Teams sind in diesem Zusammenhang äußerst nützlich. GitHub ermöglicht die Erstellung von Teams in einer Organisation, denen dann Personen hinzugefügt werden können. Diese Teams können dann in der Codeowners-Datei verwendet werden. Auf diese Weise werden Personen, die aus einem Team entfernt werden, automatisch als Codeowner für alle Repositories entfernt, in denen das Team verwendet wird.
Nachdem ich die Teams erstellt und Personen hinzugefügt hatte (ich habe dies manuell gemacht), musste ich den Teams Zugriff auf die Repositories gewähren. Dies habe ich nicht manuell gemacht, sondern über die API.
Der Befehl zum Hinzufügen eines Teams zu einem Repository sieht folgendermaßen aus:
|
1 |
> gh api -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" -f permission=push -X PUT /orgs/telekom-mms/teams/terraform-maintainers/repos/telekom-mms/examplerepo; done |
Damit hat das Team “terraform-maintainers” Zugriff auf das Repository “examplerepo” und erhält Schreibzugriff (mit -f permission=push).
Wenn ich dies nun für alle terraform-Repositories in unserer Organisation tun möchte, verwende ich eine einfache Schleife auf der Befehlszeile, um mit dem Befehl gh repo list nach Repositories zu suchen und dann nur die Repositories mit “terraform” im Namen herauszufiltern:
|
1 |
> for i in $(gh repo list telekom-mms --json name -q .[].name -L 100 | grep terraform); do gh api -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" -f permission=push -X PUT /orgs/telekom-mms/teams/terraform-maintainers/repos/telekom-mms/$i; done |
Sobald die Teams hinzugefügt wurden, kann ich sie zur Codeowners-Datei hinzufügen. Um dies über die API zu tun, muss ich im Grunde genommen den Inhalt der Datei in das Repository “PUT”en (weitere Informationen gibt es in der Dokumentation). Da es sich hierbei um Git handelt, muss ich dies in einem Commit durchführen.
Ein Commit erfordert:
- eine Commit-Nachricht – dies wird erreicht, indem das Formularfeld “message” mit der Nachricht als Wert hinzugefügt wird.
- einen “Committer” – dies ist etwas komplizierter zu erreichen. Es muss ein JSON-String mit einem Namen und einer E-Mail-Adresse hinzugefügt werden.
- den Inhalt der Datei – dies ist der Inhalt der Datei als Base64-codierter String:
|
1 2 |
> cat CODEOWNERS | base64 KiBAdGVsZWtvbS1tbXMvdGVycmFmb3JtLWFkbWlucwo= |
Der endgültige API-Aufruf sieht folgendermaßen aus:
|
1 |
> gh api --method PUT repos/telekom-mms/examplerepo/contents/CODEOWNERS -F message="add codeowners" -F committer:='{"name:"Sebastian Gumprich",email:"sebastian.gumprich@telekom.de"}' -F content="KiBAdGVsZWtvbS1tbXMvdGVycmFmb3JtLW1haW50YWluZXJzCg=="; done |
Dies kann in einer Schleife durchgeführt werden, und schon ist man fertig.
Aber natürlich macht man dabei einen Fehler und man muss dann die Datei nochmals aktualisieren. Um eine Datei mithilfe eines Commits zu aktualisieren, kann man den oben genannten Befehl nicht direkt verwenden. Man muss den “blob-SHA” der Datei angeben, die ersetzt werden soll.
Wie bekommt man diesen? Indem man die API erneut abfragt (es gibt einen Weg, dies ohne Verwendung der API zu tun, aber das habe ich nicht gemacht, da der API-Weg einfacher war):
|
1 2 |
> gh api repos/telekom-mms/examplerepo/contents/CODEOWNERS -q .sha d79b5f4ecfd52ef6ecea0a71744f6ce94a2522da |
Fügt man diesen “SHA” jetzt in den API-Aufruf ein, kann man die Datei aktualisieren:
|
1 |
> gh api --method PUT repos/telekom-mms/examplerepo/contents/CODEOWNERS -F message="update codeowners" -F committer:='{"name:"Sebastian Gumprich",email:"sebastian.gumprich@telekom.de"}' -F content="KiBAdGVsZWtvbS1tbXMvdGVycmFmb3JtLW1haW50YWluZXJzCg==" -F sha="d79b5f4ecfd52ef6ecea0a71744f6ce94a2522da" |
Mit den richtigen Codeownern an ihrem Platz war der letzte Schritt, die Branch Protection Rule festzulegen, die besagt, dass Codeowner Reviews durchführen müssen. Dies hat am längsten gedauert, da es aus der Dokumentation allein nicht möglich war, eine funktionierende Anfrage zu erstellen.
Also habe ich versucht, den existierenden Branch Protection eines Repositories zu verwenden (den man leicht mit dem Befehl gh api repos/telekom-mms/examplerepo/branches/main/protection erhalten kann), aber es war unmöglich, den folgenden Code in eine funktionierende Curl-Anfrage zu integrieren und dann über diese Curl-Anfrage zu iterieren.
Daher habe ich diesen Code verwendet:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 |
{ "url": "https://api.github.com/repos/telekom-mms/examplerepo/branches/main/protection", "required_pull_request_reviews": { "url": "https://api.github.com/repos/telekom-mms/examplerepo/branches/main/protection/required_pull_request_reviews", "dismiss_stale_reviews": false, "require_code_owner_reviews": true, "require_last_push_approval": true, "required_approving_review_count": 1, "bypass_pull_request_allowances": { "users": [], "teams": [], "apps": [ { "id": 2740, "slug": "renovate", "node_id": "MDM6QXBwMjc0MA==", "owner": { "login": "renovatebot", "id": 38656520, "node_id": "MDEyOk9yZ2FuaXphdGlvbjM4NjU2NTIw", "avatar_url": "https://avatars.githubusercontent.com/u/38656520?v=4", "gravatar_id": "", "url": "https://api.github.com/users/renovatebot", "html_url": "https://github.com/renovatebot", "followers_url": "https://api.github.com/users/renovatebot/followers", "following_url": "https://api.github.com/users/renovatebot/following{/other_user}", "gists_url": "https://api.github.com/users/renovatebot/gists{/gist_id}", "starred_url": "https://api.github.com/users/renovatebot/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/renovatebot/subscriptions", "organizations_url": "https://api.github.com/users/renovatebot/orgs", "repos_url": "https://api.github.com/users/renovatebot/repos", "events_url": "https://api.github.com/users/renovatebot/events{/privacy}", "received_events_url": "https://api.github.com/users/renovatebot/received_events", "type": "Organization", "site_admin": false }, "name": "Renovate", "description": "[omitted for brevity]", "external_url": "https://www.mend.io/free-developer-tools/renovate/", "html_url": "https://github.com/apps/renovate", "created_at": "2017-06-02T07:04:12Z", "updated_at": "2023-11-06T09:25:36Z", "permissions": { "administration": "read", "checks": "write", "contents": "write", "emails": "read", "issues": "write", "members": "read", "metadata": "read", "packages": "read", "pull_requests": "write", "statuses": "write", "vulnerability_alerts": "read", "workflows": "write" }, "events": [ "issues", "pull_request", "push", "repository" ] } ] } }, "required_signatures": { "url": "https://api.github.com/repos/telekom-mms/examplerepo/branches/main/protection/required_signatures", "enabled": false }, "enforce_admins": { "url": "https://api.github.com/repos/telekom-mms/examplerepo/branches/main/protection/enforce_admins", "enabled": false }, "required_linear_history": { "enabled": false }, "allow_force_pushes": { "enabled": false }, "allow_deletions": { "enabled": false }, "block_creations": { "enabled": false }, "required_conversation_resolution": { "enabled": false }, "lock_branch": { "enabled": false }, "allow_fork_syncing": { "enabled": false } } |
Und dann versucht, ihn auf eine minimale funktionierende Anfrage zu reduzieren. Das hat eine Weile gedauert, aber hier ist das endgültige Ergebnis:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
> curl -X PUT -H "Authorization: token $GITHUB_TOKEN" -H "Accept: application/vnd.github.v3+json" https://api.github.com/repos/telekom-mms/examplerepo/branches/main/protection -d '{ "required_pull_request_reviews": { "dismiss_stale_reviews": false, "require_code_owner_reviews": true, "require_last_push_approval": true, "required_approving_review_count": 1, "bypass_pull_request_allowances": { "apps": ["branch-protection-as-code"] } }, "enforce_admins": false, "restrictions": null, "required_status_checks": null }'; done |
Wenn man über diesen Code iteriert, funktioniert es. Ich kann nun unsere Repositories im großen Maßstab verwalten (Und jetzt: kann mir jetzt jemand bitte die bereits bestehende Lösung sagen, um dies zu tun?)
Weiterführende Informationen
Software Engineering Community – vernetzt, innovativ, geschäftsrelevant
>Zum Blogbeitrag & zur Podcast-Folge
Linux und Open Source Enthusiast. Aus dem traditionellen Betrieb kommend, schlage ich jetzt Brücken zwischen Betrieb und Entwicklung und tauche nebenbei in die Cloud-Native Landschaft ein.
