Skip to content

Latest commit

 

History

History
148 lines (121 loc) · 8.02 KB

README.md

File metadata and controls

148 lines (121 loc) · 8.02 KB
Raw

Manage github organisation membership with Google Workspace user accounts

Known Vulnerabilities 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: 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