initial commit

Signed-off-by: Tim Beermann <[email protected]>

.flake8

@@ -0,0 +1,2 @@
+[flake8]
+ignore = E501

.github/workflows/build_container.yml

@@ -0,0 +1,37 @@
+---
+name: Build GHOM
+
+"on":
+  workflow_dispatch:
+  push:
+    branches:
+      - 'main'
+    paths:
+      - 'Dockerfile'
+      - 'requirements.txt'
+      - 'ghom'
+
+jobs:
+  build-ghom:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone current repository
+        uses: actions/checkout@v3
+
+      - name: Build using buildah
+        id: build
+        uses: redhat-actions/buildah-build@v2
+        with:
+          image: ghcr.io/tibeer/ghom
+          tags: ghcr.io/tibeer/ghom:latest
+          containerfiles: |
+            ./Containerfile
+
+      - name: Push to ghcr.io
+        uses: redhat-actions/push-to-registry@v2
+        with:
+          image: ${{ steps.build.outputs.image }}
+          tags: ${{ steps.build.outputs.tags }}
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ github.token }}

.github/workflows/ghom_workflow.yml.example

@@ -0,0 +1,34 @@
+---
+name: Run GHOM
+
+"on":
+  workflow_dispatch:
+  push:
+    branches:
+      - 'main'
+    paths:
+      - 'ghom.yaml'
+
+jobs:
+  run-ghom:
+    permissions: write-all
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone current repository
+        uses: actions/checkout@v3
+        # If you use this workflow on a private repository, uncommit this and adapt accordingly
+        #with:
+        #  repository: tibeer/ghom
+        #  token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Run ghom
+        uses: tibeer/ghom@main
+        with:
+          ghom_token: ${{ secrets.ghom_token }}
+          # The default path of your ghom config file. Please note that this has to be an
+          # absolute path (/github/workspace is the default path for your checked our repo)
+          #ghom_config: '/github/workspace/ghom.yaml'
+          # Enable debug mode. Do not perform any changes, only print what would be done.
+          # Please note, that this might result in a few errors, because ghom requires
+          # changes to be made for depencies (e.g. team-repos require repos to be available).
+          #ghom_dry: 'False'

.gitignore

@@ -0,0 +1 @@
+*.py[cod]

Containerfile

@@ -0,0 +1,11 @@
+FROM python:3.10
+
+WORKDIR /usr/src/app
+
+COPY requirements.txt ./
+
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY ghom /usr/local/lib/python3.10/site-packages/ghom
+
+ENTRYPOINT ["/usr/local/bin/python", "-m", "ghom.main"]

README.md

@@ -0,0 +1,51 @@
+# GHOM - GitHub Organization Manager - WIP!!!
+
+Ghom is a tool to manage your GitHub organisation.
+Currently work in progress.
+
+## How to use
+
+In any case you need to change the settings in your organization to allow changes from actions. Head over to <https://github.com/organizations/YOUR_ORG/settings/actions>, scroll down to _Workflow permissions_ and select __Read and write permissions__. Otherwise github actions cannot change settings on your organization.
+
+### Automated (recommended)
+
+1. Create a fresh new GitHub organization. You may use ghom also on an existing org, but I will not guarantee for flawless integration. In any case: Use with caution. 
+2. Create a repository containing a `ghom.yaml` file.
+3. Create a workflow like shown [here](.github/workflows/ghom_workflow.yml.example) in the same repository.
+4. Trigger the workflow it by either merging a PR to main (containing a change in `ghom.yaml`) or by manual execution.
+
+### Manual
+
+```sh
+export GITHUB_REPOSITORY_OWNER=ghomtest
+export INPUT_GHOM_CONFIG=ghom.yaml
+export INPUT_GHOM_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+export INPUT_GHOM_DRY=False
+python3 -m ghom.main
+```
+
+## FAQ
+
+Q: How to deal with private repositories?\
+A: Look [here](docs/private_repositories.md)
+
+Q: Why do you have to use a GHP token?\
+A: A GitHub app would require a running server. I could provide one, but this would have the drawback, that the rate limit would affect all users simultaniously. Either we "gain" more possible requests than needed. Or a user with a humoungus organization size installs the app and will block the app for all users...
+
+Q: How to deal with my large organization that is too large to fit into 5000 api requests per hour?\
+A: Switch back to manual adjustment or split the ghom file into multiple parts. The principle is basically the same as if you would use [private repositories](docs/private_repositories.md). If you have another (elegant) solution, let me know!
+
+Q: Why do repositories have to be initialized with the default README.md file?\
+A: Otherwise branch protections cannot be set.
+
+Q: Why is the code so redundant?\
+A: To keep it simple. If you have a solution, that removes redundant code while keeping it easy to maintain and understand, feel free to create a pull request.
+
+Q: Why is there no script to generate a `ghom.yaml` file from an existing org?\
+A: I had no interest in creating one yet. Chances are low that I find the motivation in the future :)
+
+## Known issues
+
+Branch protection rules are a bit flanky. You can only delete them, if default rules are set. Leaving them empty would result in keeping the current rules.
+
+If you create a new team, the owner of the organization will be added automatically to this team. Therefore you'll see first the creation of the and and second the deletion of a team member. This behavior is due to GitHub internal handeling of these API requests and cannot be changed.

action.yml

@@ -0,0 +1,21 @@
+---
+name: 'ghom-ghom'
+description: 'GitHub Organization Manager'
+inputs:
+  ghom_token:
+    description: 'Provide a user GHP (as a secret)'
+    required: true
+  ghom_config:
+    description: 'Provide an alternative path to the ghom config file'
+    required: false
+    default: "/github/workspace/ghom.yaml"
+  ghom_dry:
+    description: 'Enable dry run mode'
+    required: false
+    default: "False"
+runs:
+  using: 'docker'
+  image: 'docker://ghcr.io/tibeer/ghom:1.0.0'
+branding:
+  color: white
+  icon: users

docs/private_repositories.md

@@ -0,0 +1,16 @@
+# Private repositories
+
+You can split `ghom.yaml` files into multiple parts or even across different repositories.
+Both methods have in common that you require more than one workflow.
+
+Because of this, one workflow might interfer with the other one, especially when it comes to deletion.
+Let's assume the following scenario:
+
+- Workflow A takes care of public repositories
+- Workflow B takes care of private repositories and also teams (only global teams, not repo specific ones), because they should be kept private
+
+If workflow A has `allow_team_removal` set to __true__, it will most likely happen that all your teams managed by workflow B will be deleted. This is not a flaw in the code but rather originates from the design conzept. Ghom indends to be idempotent, so it works as expected.
+
+Rather use multiple ghom files, all with e.g. `allow_team_removal` all set to __false__ except for one file. This file should then also contain all teams.
+
+By using this method you can A) hide sensitive content in private repositories and B) can bypass API rate limits. Though, you might need multiple bot accounts with seperate GHP tokens.

docs/release.md

@@ -0,0 +1,54 @@
+# Release
+
+## How to create a release
+
+This is mainly for @tibeer to create a new release of this action.
+
+1. Tag the container with a new version:
+
+   Always create a new tag for all three possible tags: `major`, `major.minor`, `major.minor.patch`
+
+   ```sh
+   # define new tag
+   export MAJOR=1
+   export MINOR=51
+   export PATCH=3
+   # get latest image
+   podman pull "ghcr.io/tibeer/ghom:latest"
+   # push new tags
+   podman push "ghcr.io/tibeer/ghom:latest" "ghcr.io/tibeer/ghom:${MAJOR}"
+   podman push "ghcr.io/tibeer/ghom:latest" "ghcr.io/tibeer/ghom:${MAJOR}.${MINOR}"
+   podman push "ghcr.io/tibeer/ghom:latest" "ghcr.io/tibeer/ghom:${MAJOR}.${MINOR}.${PATCH}"
+   # also remove latest image
+   podman image rm "ghcr.io/tibeer/ghom:latest"
+   ```
+
+2. Change the `action.yml` file container tag to the most detailed version: `major.minor.patch`
+3. Tag the repository with a new version
+
+   ```sh
+   # define new tag
+   export MAJOR=1
+   export MINOR=51
+   export PATCH=3
+   # tag current state
+   git tag "${MAJOR}" main
+   git tag "${MAJOR}.${MINOR}" main
+   git tag "${MAJOR}.${MINOR}.${PATCH}" main
+   # push tags
+   git push origin "${MAJOR}"
+   git push origin "${MAJOR}.${MINOR}"
+   git push origin "${MAJOR}.${MINOR}.${PATCH}"
+   ```
+
+4. Create a new release: <https://github.com/tibeer/ghom/releases/new>
+
+## Release pattern
+
+We'll use [semver](https://semver.org/) vor versioning (and we'll not use a stupid "v" prefix).
+
+1. Major: Something drastically changes (e.g. PyGithub is replaced by something else, ghom config file is not backwards compatible)
+2. Minor: Functionality is added
+3. Patch: Bug fixes
+
+Testing will always be done on the "latest" tag.

ghom.yaml

@@ -0,0 +1,97 @@
+---
+allow_team_removal: true
+allow_team_repo_removal: true
+allow_team_member_removal: true
+allow_member_removal: true
+allow_label_removal: true
+allow_repository_removal: false
+owners:
+  - tibeer
+members:
+  - tibeerbot
+teams:
+  admins:
+    description: ""
+    private: false
+    maintainers:
+      - tibeerbot
+    members:
+      - tibeerbot
+  maintainers:
+    description: ""
+    private: false
+    maintainers:
+      - tibeerbot
+  ops:
+    description: "Ops team"
+    private: false
+repository_defaults:
+  has_wiki: false
+  has_issues: true
+  has_projects: false
+  has_downloads: false  # no idea, what this sets, cannot find it
+  allow_squash_merge: true
+  allow_merge_commit: false
+  allow_rebase_merge: false
+  delete_branch_on_merge: true
+  homepage: ""
+  description: ""
+  private: false
+  default_branch_protection:
+    branch_name: main
+    active: true
+    required_pull_request_review_count: 0  # 1-6, 0 to disable
+    required_pull_request_owner_review: true
+    enforce_admins: false
+    #allow_force_pushes: false  # Not implemented yet in PyGithub
+  default_teams:
+    # permissions can be one of: pull, triage, push, maintain, admin
+    admins: "admin"
+    maintainers: "maintain"
+repositories:
+  .github:
+    archived: false
+    homepage: "https://github.com/ghomtest"
+    default_branch_protection:
+      branch_name: gh_pages
+      active: false
+    labels:
+      - name: documentation
+        description: "overwrite documentation label colors"
+        color: a2ffff
+      - name: addition
+        description: "special label only for this repo"
+        color: a00000
+    teams:
+      ops: "push"
+  ghom:
+  repo02:
+  repo03:
+labels:
+  - name: bug
+    description: "Something isn't working"
+    color: d73a4a
+  - name: documentation
+    description: "Improvements or additions to documentation"
+    color: 0075ca
+  - name: duplicate
+    description: "This issue or pull request already exists"
+    color: cfd3d7
+  - name: enhancement
+    description: "New feature or request"
+    color: a2eeef
+  - name: good first issue
+    description: "Good for newcomers"
+    color: 7057ff
+  - name: help wanted
+    description: "Extra attention is needed"
+    color: 008672
+  - name: invalid
+    description: "This doesn't seem right"
+    color: e4e669
+  - name: question
+    description: "Further information is requested"
+    color: d876e3
+  - name: wontfix
+    description: "This will not be worked on"
+    color: ffffff