github.com/munnerz/test-infra@v0.0.0-20190108210205-ce3d181dc989/prow/cmd/peribolos/README.md (about)

     1  # Peribolos Documentation
     2  
     3  Peribolos allows the org settings, teams and memberships to be declared in a yaml file. Github is then updated to match the declared configuration.
     4  
     5  See the [kubernetes/org] repo, in particular the [merge] and [`update.sh`] parts of that repo for this tool in action.
     6  
     7  ### Etymology
     8  
     9  A [peribolos] is a wall that encloses a court in Greek/Roman architecture.
    10  
    11  ## Org configuration
    12  
    13  Extend the primary prow [`config.yaml`] document to include a top-level `orgs` key that looks like the following:
    14  
    15  ```yaml
    16  orgs:
    17    this-org:
    18      # org settings
    19      company: foo
    20      email: foo
    21      name: foo
    22      description: foo
    23      has_organization_projects: true
    24      has_repository_projects: true
    25      default_repository_permission: read
    26      members_can_create_repositories: false
    27  
    28      # org member settings
    29      members:
    30      - anne
    31      - bob
    32      admins:
    33      - carl
    34  
    35      # team settings
    36      teams:
    37        node:
    38          # team config
    39          description: people working on node backend
    40          privacy: closed
    41          previously:
    42          - backend  # If a backend team exists, rename it to node
    43  
    44          # team members
    45          members:
    46          - anne
    47          maintainers:
    48          - jane
    49        another-team:
    50          ...
    51        ...
    52    that-org:
    53      ...
    54  ```
    55  
    56  This config will:
    57  * Ensure the org settings match the following:
    58    - Set the company, email, name and descriptions fields for the org to foo
    59    - Allow projects to be created at the org and repo levels
    60    - Give everyone read access to repos by default
    61    - Disallow members from creating repositories
    62  * Ensure the following memberships exist:
    63    - anne and bob are members, carl is an admin
    64  * Configure the node and another-team in the following manner:
    65    - Set node's description and privacy setting.
    66    - Rename the backend team to node
    67    - Add anne as a member and jane as a maintainer to node
    68    - Similar things for another-team (details elided)
    69  
    70  Note that any fields missing from the config will not be managed by peribolos. So if description is missing from the org setting, the current value will remain.
    71  
    72  For more details please see GitHub documentation around [edit org], [update org membership], [edit team], [update team membership].
    73  
    74  ### Initial seed
    75  
    76  Peribolos can dump the current configuration to an org. For example you could dump the kubernetes org do the following:
    77  
    78  ```console
    79  $ bazel run //prow/cmd/peribolos -- --dump kubernetes-sigs --github-token-path ~/github-token | tee ~/current.yaml # --tokens=0 to disable throttling
    80  INFO: Analysed target //prow/cmd/peribolos:peribolos (0 packages loaded).
    81  INFO: Found 1 target...
    82  Target //prow/cmd/peribolos:peribolos up-to-date:
    83    bazel-bin/prow/cmd/peribolos/darwin_amd64_pure_stripped/peribolos
    84  INFO: Elapsed time: 0.533s, Critical Path: 0.18s
    85  INFO: 0 processes.
    86  INFO: Build completed successfully, 1 total action
    87  INFO: Running command line: bazel-bin/prow/cmd/peribolos/darwin_amd64_pure_stripped/peribolos --dump kubernetes-sigs
    88  INFO: Build completed successfully, 1 total action
    89  {"client":"github","component":"peribolos","level":"info","msg":"Throttle(300, 100)","time":"2018-09-28T13:17:42-07:00"}
    90  {"client":"github","component":"peribolos","level":"info","msg":"GetOrg(kubernetes-sigs)","time":"2018-09-28T13:17:42-07:00"}
    91  {"client":"github","component":"peribolos","level":"info","msg":"ListOrgMembers(kubernetes-sigs, admin)","time":"2018-09-28T13:17:42-07:00"}
    92  {"client":"github","component":"peribolos","level":"info","msg":"ListOrgMembers(kubernetes-sigs, member)","time":"2018-09-28T13:17:43-07:00"}
    93  {"client":"github","component":"peribolos","level":"info","msg":"ListTeams(kubernetes-sigs)","time":"2018-09-28T13:17:45-07:00"}
    94  {"client":"github","component":"peribolos","level":"info","msg":"ListTeamMembers(2671356, maintainer)","time":"2018-09-28T13:17:46-07:00"}
    95  {"client":"github","component":"peribolos","level":"info","msg":"ListTeamMembers(2671356, member)","time":"2018-09-28T13:17:46-07:00"}
    96  ...
    97  admins:
    98  - calebamiles
    99  - cblecker
   100  - etc
   101  billing_email: secret@example.com
   102  company: ""
   103  default_repository_permission: read
   104  description: Org for Kubernetes SIG-related work
   105  email: ""
   106  has_organization_projects: true
   107  has_repository_projects: true
   108  location: ""
   109  members:
   110  - ameukam
   111  - amwat
   112  - ant31
   113  - etc
   114  teams:
   115    application-admins:
   116      description: admin access to application
   117      maintainers:
   118      - kow3ns
   119      members:
   120      - mattfarina
   121      - prydonius
   122      privacy: closed
   123    architecture-tracking-admins:
   124      description: admin permission for architecture-tracking
   125      maintainers:
   126      - jdumars
   127      - bgrant0607
   128      privacy: closed
   129    # etc
   130  ```
   131  
   132  Open `~/current.yaml` and then delete any metadata you don't want peribolos to manage (such as billing_email, or all the teams, etc).
   133  
   134  Apply this config in dry-run mode to see what would happen (hopefully nothing since you just created it):
   135  
   136  ```console
   137  $ bazel run //prow/cmd/peribolos -- --config-path ~/current.yaml --github-token-path ~/github-token # --confirm
   138  
   139  {"client":"github","component":"peribolos","level":"info","msg":"GetOrg(kubernetes-sigs)","time":"2018-09-27T23:07:13Z"}
   140  {"client":"github","component":"peribolos","level":"info","msg":"ListOrgInvitations(kubernetes-sigs)","time":"2018-09-27T23:07:13Z"}
   141  {"client":"github","component":"peribolos","level":"info","msg":"ListOrgMembers(kubernetes-sigs, admin)","time":"2018-09-27T23:07:13Z"}
   142  {"client":"github","component":"peribolos","level":"info","msg":"ListOrgMembers(kubernetes-sigs, member)","time":"2018-09-27T23:07:14Z"}
   143  ...
   144  ```
   145  
   146  
   147  
   148  ## Settings
   149  
   150  In order to mitigate the chance of applying erroneous configs, the peribolos binary includes a few safety checks:
   151  
   152  * `--required-admins=` - a list of people who must be configured as admins in order to accept the config (defaults to empty list)
   153  * `--min-admins=5` - the config must specify at least this many admins
   154  * `--require-self=true` - require the bot applying the config to be an admin.
   155  
   156  These flags are designed to ensure that any problems can be corrected by rerunning the tool with a fixed config and/or binary.
   157  
   158  * `--maximimum-removal-delta=0.25` - reject a config that deletes more than 25% of the current memberships.
   159  
   160  This flag is designed to protect against typos in the configuration which might cause massive, unwanted deletions. Raising this value to 1.0 will allow deleting everyone, and reducing it to 0.0 will prevent any deletions.
   161  
   162  * `--confirm=false` - no github mutations will be made until this flag is true. It is safe to run the binary without this flag. It will print what it would do, without actually making any changes.
   163  
   164  
   165  See `bazel run //prow/cmd/peribolos -- --help` for the full and current list of settings that can be configured with flags.
   166  
   167  
   168  
   169  [`config.yaml`]: /prow/config.yaml
   170  [edit team]: https://developer.github.com/v3/teams/#edit-team
   171  [edit org]: https://developer.github.com/v3/orgs/#edit-an-organization
   172  [peribolos]: https://en.wikipedia.org/wiki/Peribolos
   173  [update org membership]: https://developer.github.com/v3/orgs/members/#add-or-update-organization-membership
   174  [update team membership]: https://developer.github.com/v3/teams/members/#add-or-update-team-membership
   175  [merge]: https://github.com/kubernetes/org/tree/master/cmd/merge
   176  [kubernetes/org]: https://github.com/kubernetes/org
   177  [`update.sh`]: https://github.com/kubernetes/org/blob/master/admin/update.sh