GitHub Organization Member Email Report Action

A GitHub Action to generate a report retrieving member email addresses from a GitHub cloud organization where possible.

This Action tries to retrieve the three types of user email from the personal user account and linked SSO identity for GitHub cloud organization members.

The three GitHub user email types which could be retrieved are:

• The account email (if not set to hidden by the user)
• The verified email (if a verified domain is set which matches the user account email domain)
• The organization SSO linked identity (nameID) email (if SAML SSO is enabled)

💡 When multiple verified domain names are set, more than a single match per member can occur, the verified email field in the report would then return multiple results.

Usage

By default the example workflow below runs on a monthly schedule but the Action can also be triggered manually using a workflow_dispatch.

name: Member Email Report

on:
  schedule:
    # Runs on the first day of every month at 00:00 UTC
    #
    #        ┌────────────── minute
    #        │ ┌──────────── hour
    #        │ │ ┌────────── day (month)
    #        │ │ │ ┌──────── month
    #        │ │ │ │ ┌────── day (week)
    - cron: '0 0 1 * *'
  workflow_dispatch:

jobs:
  member-email-report:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Get member emails
        uses: nicklegan/[email protected]
        with:
          token: ${{ secrets.ORG_TOKEN }}
        # org: ''
        # sort: 'userName'
        # sort-order: 'asc'
        # single-report: 'false'
        # json: 'false'
        # appid: ${{ secrets.APPID }}
        # privatekey: ${{ secrets.PRIVATEKEY }}
        # installationid: ${{ secrets.INSTALLATIONID }}

GitHub secrets

Name	Value	Required
ORG_TOKEN	An user:email, repo, admin:orgscoped Personal Access Token	true
ACTIONS_STEP_DEBUG	true Enables diagnostic logging	false

💡 Disable token expiration to avoid failed workflow runs when running on a schedule.

Action inputs

Name	Description	Default	Location	Required
org	Organization different than workflow context		workflow.yml	false
sort	CSV column used to sort report: userName, fullName, publicEmail, verifiedEmail, ssoEmail, updatedAt, createdAt	userName	workflow.yml	false
sort-order	CSV column sort order: asc or desc	asc	workflow.yml	false
single-report	Setting to generate an additional timestamped CSV report per workflow run	false	workflow.yml	false
json	Setting to generate an additional report in JSON format	false	workflow.yml	false
committer-name	The name of the committer that will appear in the Git history	github-actions	action.yml	false
committer-email	The committer email that will appear in the Git history	[email protected]	action.yml	false

CSV layout

Column	Description
Username	GitHub username
Full name	GitHub profile name
Public email	GitHub account email
Verified email	GitHub verified domain email
SSO email	GitHub linked NameID email
Updated	The date the user settings were last updated
Created	The date the user account was created

A CSV report file will be saved in the repository reports folder using the following naming format: organization-date.csv.

If the single-report option is enabled in action.yml an additional unique report per workflow run will be generated in the reports/single folder.

GitHub App authentication

In some scenarios it might be preferred to authenthicate as a GitHub App rather than using a personal access token.

The following features could be a benefit authenticating as a GitHub App installation:

• The GitHub App is directly installed on the organization, no seperate user account is required.
• A GitHub App has more granular permission options than a personal access token.
• To avoid hitting the 5000 requests per hour GitHub API rate limit, authenticating as a GitHub App installation would increase the API request limit.

💡 When using GitHub App authentication, the organization members can only be retrieved from the organization the GitHub App is installed in.

Configuration

Register a new organization/personal owned GitHub App with the below permissions:

GitHub App Permission	Access
Organization Permissions:Administration	read
Organization Permissions:Members	read
Repository Permissions:Contents	read and write
User Permissions:Email addresses	read

After registration install the GitHub App to your organization. Store the below App values as secrets.

GitHub App secrets

Name	Value	Required
APPID	GitHub App ID number	true
PRIVATEKEY	Content of private key .pem file	true
INSTALLATIONID	GitHub App installation ID number	true