update readme and provide a github action

Author: chrisns

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ on:
       - created
 
 jobs:
-  test:
+  build:
     runs-on: ubuntu-latest
 
     steps:
@@ -29,23 +29,7 @@ jobs:
 
       - run: npm run lint
 
-      - run: |
-          set -a
-          . ./.env.example
-          set +a
-          npm run test
-
-      - uses: coverallsapp/github-action@master
-        with:
-          github-token: ${{ secrets.github_token }}
-
-      - name: Login to dockerhub
-        if: ${{ github.event_name != 'pull_request' }}
-        uses: docker/login-action@v1
-        with:
-          registry: docker.pkg.github.com
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
+      - run: npm run test
 
       - id: docker_meta
         uses: crazy-max/ghaction-docker-meta@v1
@@ -59,10 +43,15 @@ jobs:
             org.opencontainers.image.vendor=appvia
             org.opencontainers.image.documentation=https://github.com/appvia/githubUserManager
             org.opencontainers.image.authors=Chris Nesbitt-Smith <chris.nesbitt-smith@appvia.io>
-            org.opencontainers.image.url=https://github.com/appvia/githubUserManager
             maintainer=appvia
 
-
+      - name: Login to docker registry
+        if: ${{ github.event_name != 'pull_request' }}
+        uses: docker/login-action@v1
+        with:
+          registry: docker.pkg.github.com
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Push to GitHub Packages
         uses: docker/build-push-action@v2

README.md

@@ -1,5 +1,20 @@
+# Manage github organisation membership with Google Workspace user accounts
+
+[![Known Vulnerabilities](https://snyk.io/test/github/appvia/githubUserManager/badge.svg)](https://snyk.io/test/github/appvia/githubUserManager)
+[![GitHub license](https://img.shields.io/github/license/appvia/githubUserManager)](https://github.com/appvia/githubUserManager/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/appvia/githubusermanager)](https://github.com/appvia/githubusermanager/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/appvia/githubusermanager)](https://github.com/appvia/githubusermanager/network)
+[![GitHub issues](https://img.shields.io/github/issues/appvia/githubusermanager)](https://github.com/appvia/githubusermanager/issues)
+[![ci](https://github.com/appvia/githubUserManager/actions/workflows/ci.yml/badge.svg)](https://github.com/appvia/githubUserManager/actions/workflows/ci.yml)
+
+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](https://support.google.com/a/answer/6208725?hl=en#zippy=%2Cadd-a-new-custom-attribute)
 
     1. Go to https://admin.google.com/ac/customschema
@@ -62,7 +77,46 @@
     1. 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
+### Run
+
+#### Github Action:
+
+```yaml
+# ./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/githubUserManager@v1
+        with:
+          google-email-address: hello@example.com
+          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.GITHUB_PRIVATE_KEY }}
+          ignored-users: user1,user2
+```
+
+#### Docker
+
+1. make an [env file](https://www.digitalocean.com/community/tutorials/how-to-read-and-set-environmental-and-shell-variables-on-linux) with the [below table](#Setup-environment-variables)
+1. `docker run --env-file .env docker.pkg.github.com/appvia/githubusermanager/githubusermanager:main`
+
+#### node/lambda/cloud run/ something else
+
+1.  clone this repo
+1.  `npm install --production`
+1.  `npm start` (with the with the [below environment variables table](#Setup-environment-variables) set)
 
 ### Setup environment variables
 

action.yml

@@ -0,0 +1,49 @@
+name: 'Google workspace user to GitHub Org User'
+description: 'Manage GitHub organisation membership with Google Workspace user accounts'
+author: Chris Nesbitt-Smith 
+inputs:
+  google-email-address:
+    description: 'Email address to assume to, needs to be an workspace admin'
+    required: true
+  google-credentials:
+    description: 'Base64'd json as downloaded from the google service account creation step'
+    required: true
+  add-users:
+    description: 'Set to TRUE to add users to the github organisation'
+    required: true
+  remove-users:
+    description: 'Set to TRUE to remove users from the github organisation'
+    required: false
+  exit-code-on-missmatch:
+    description: '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'
+    required: false
+  github-org:
+    description: 'GitHub Organization  '
+    required: true
+  github-app-id:
+    description: 'GitHub App ID'
+    required: true
+  github-installation-id:
+    description: 'Github App Installation ID'
+    required: true
+  github-private-key:
+    description: 'Base64'd private key as downloaded from github application registration step'
+    required: true
+  ignored-users:
+    description: 'Comma separated list of user ids to totally ignore always, useful for owners of an org you don't accidentally removed'
+    required: false
+runs:
+  using: 'docker'
+  image: 'Dockerfile'
+  env:
+     GOOGLE_EMAIL_ADDRESS: ${{ inputs.google-email-address }}
+     GOOGLE_CREDENTIALS: ${{ inputs.google-credentials }}
+     ADD_USERS: ${{ inputs.add-users }}
+     REMOVE_USERS: ${{ inputs.remove-users }}
+     EXIT_CODE_ON_MISMATCH: ${{ inputs.exit-code-on-missmatch }}
+     GITHUB_ORG: ${{ inputs.github-org }}
+     GITHUB_APP_ID: ${{ inputs.github-app-id }}
+     GITHUB_INSTALLATION_ID: ${{ inputs.github-installation-id }}
+     GITHUB_PRIVATE_KEY: ${{ inputs.github-private-key }}
+     IGNORED_USERS: ${{ inputs.ignored-users }}
+