Skip to content

README.md

Latest commit

 

History

History
165 lines (141 loc) · 9.48 KB

README.md

File metadata and controls

165 lines (141 loc) · 9.48 KB
Raw

Manage github organisation membership with Google Workspace user accounts

GitHub license GitHub stars GitHub forks GitHub issues ci

Manages who is in your GitHub organization based on a custom property in their Google Workspace profile, allowing for seamless JML (Joiner mover leaver) process, if allowed removing/disabling an account in the Google Workspace will remove the user from the GitHub; similarly adding a user also works the same way. If you don't want to run it in destructive mode it can be configured to exit with a non-zero exit code so that you know to go and manually make the changes.

Right now this only handles the organization membership, it does not touch team membership, or level of membership; the main focus is to draw alert when the configuration isn't as expected, these features could be added in future.

Deployment

Collect the secrets

  1. Add a custom attribute on the users

    1. Go to https://admin.google.com/ac/customschema
    2. Enter
      • Category: Accounts
      • Description: Accounts held elsewhere to link in
      • Custom fields:
        • name: github
        • info type: text
        • visibility: Visible to the organisation
        • no. of values: multi-value

  2. Add values to custom attributes for the users

    1. Go to https://admin.google.com/ac/users
    2. Click a user to edit them
    3. Click 'user information'
    4. Under Accounts, click github
    5. Add all the github accounts for that user
    6. Click Save

  3. Make a gcp project

    1. Enable the Admin SDK API
    2. Create credentials
    • Which API are you using?: Admin SDK API
    • Are you planning to use this API with App Engine or Compute Engine: no
    • Service account name: githubusermanager
    • Role: [none]
    • Key type: JSON
    • Click Continue, then confirm CREATE WITHOUT ROLE
    • Edit the user, Click Enable G Suite domain-wide delegation
    • Product name for the consent screen: githubusermanager
    1. Delegate domain-wide authority to your service account

  4. Register new GitHub App

    1. https://github.com/settings/organizations
    • Click Settings on your organization
    • Click Developer settings
    • Click GitHub Apps
    • Click New GitHub App
    1. Enter:
    • GitHub App name: Google workspace github users
    • Homepage URL: github.com
    • Webhook
      • Active uncheck
    • Organization permissions
      • Members: Read-only, or Read-Write if you want it to
    • Where can this GitHub App be installed? Only on this account
    1. Click Generate a private key (should download a .pem)
    2. Click Install App
    3. Click Install
    4. Click Install
    • take node of the url, it'll look something like: github.com/organizations/myorg/settings/installations/15627551, the installationId is the last number 15627551

Run

Github Action:

# ./.github/workflows/org-membership.yml
name: Github Org Membership

on:
  schedule:
    - cron: '*/5 * * * *'
jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Github Org Membership Manager
        uses: reMarkable/githubUserManager@v1
        with:
          google-email-address: hello@example.com
          google-credentials: ${{ secrets.GOOGLE_CREDENTIALS }}
          add-users: 'false'
          remove-users: 'false'
          exit-code-on-mismatch: '1'
          github-org: 'myorg'
          github-app-id: 1234
          github-installation-id: 12345
          github-private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
          ignored-users: user1,user2
          sync-team: 'true'
          team-slug: 'remarkable'

Add a dependabot configuration to always get updates!

# ./.github/dependabot.yml
version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: daily

Docker

This action runs as a Docker container action: GitHub builds the image from the Dockerfile at the exact ref you pin the action to, so you can reference an immutable commit SHA and there is no separately published image tag to bump before a release.

Inputs are read directly from the GitHub Action inputs (exposed by the runner as INPUT_* environment variables). To run the container by hand, set the same inputs with the INPUT_ prefix and the input name upper-cased, e.g. INPUT_GITHUB-ORG, INPUT_ADD-USERS:

docker build -t githubusermanager .
docker run --rm \
  -e INPUT_GOOGLE-EMAIL-ADDRESS=foo@example.com \
  -e INPUT_GITHUB-ORG=myorg \
  # ...the remaining inputs from the table below... \
  githubusermanager

Go / lambda / cloud run / something else

  1. Clone this repo
  2. go build -o githubusermanager .
  3. ./githubusermanager (with the INPUT_* variables from the table below set)

Action inputs

Inputs use the action input names below; when running the container directly set them as INPUT_<NAME> environment variables (upper-cased input name).

Input Description Example Default
google-email-address Email address to assume to, needs to be an workspace admin foo@example.com null
google-credentials Base64'd json as downloaded from the google service account creation step Zm9vCg== null
add-users Set to TRUE to add users to the github organisation TRUE false
remove-users Set to TRUE to remove users from the github organisation TRUE false
remove-suspended_users Set to TRUE to remove users from the github organisation that are suspended in Google TRUE false
exit-code-on-mismatch Exit code to use when there's a mismatch, useful when combined with add-users and remove-users to be used in a dry-run mode 1 0
max-remove-users Safety limit on how many users may be removed in a single run 100 100
github-org GitHub Organization chrisnstest null
github-app-id GitHub App ID 106341 null
github-installation-id Github App Installation ID 15627551 null
github-private-key Base64'd private key as downloaded from github application registration step Zm9vCg== null
ignored-users Comma separated list of user ids to totally ignore always, useful for owners of an org you don't want accidentally removed owner1,owner2 null
sync-team Set to TRUE to ensure every org member is added to the team named in team-slug TRUE false
team-slug Slug of the team every org member should be added to, e.g. to grant PR rights to shared repos remarkable null
debug Set to TRUE to enable debug level logging TRUE false