Manage github organisation membership with Google Workspace user accounts

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
   • https://admin.google.com/ac/owl/domainwidedelegation
   • Client ID: client id from user
   • OAuth scopes:
     • https://www.googleapis.com/auth/admin.directory.user.readonly

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: appvia/[email protected]
        with:
          google-email-address: [email protected]
          google-credentials: ${{ secrets.GOOGLE_CREDENTIALS }}
          add-users: 'false'
          remove-users: 'false'
          exit-code-on-missmatch: '1'
          github-org: 'myorg'
          github-app-id: 1234
          github-installation-id: 12345
          github-private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
          ignored-users: user1,user2
          github-token: ${{ secrets.GITHUB_TOKEN }}
          github-actor: ${{ github.actor }}

Add a dependabot configuration to always get updates!

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

Docker

1. Make an env file with the below table
2. docker run --env-file .env docker.pkg.github.com/appvia/githubusermanager/githubusermanager:main

node/lambda/cloud run/ something else

1. Clone this repo
2. npm install --production
3. npm start (with the with the below environment variables table set)

Setup environment variables

Environment Variable	Description	Example	Default
GOOGLE_EMAIL_ADDRESS	Email address to assume to, needs to be an workspace admin	[email protected]	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
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
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