How to Remove a Dormant GitHub User
This document provides instructions for identifying and removing dormant GitHub users within the Ministry of Justice GitHub Enterprise. By following this runbook, the Operations Engineering team can optimise the use of GitHub licenses, reduce unnecessary costs, and maintain security by ensuring only active users can access enterprise resources.
What is a Dormant GitHub User?
According to GitHub, A dormant GitHub user is an account that has not performed any activity within the last 90 days in an Enterprise account. Our Enterprise account has two organisations with two different types of users:
ministryofjustice: traditionally contains developers and folks making changes to codebases.moj-analytical-services: contains a whole spectrum of technical and non-technical people.
The GitHub documentation provides a detailed list of activities that define user activity in GitHub.
Many services in the Digital space use GitHub as an identity provider to access their systems. Cloud Platform, Analytical Platform, and Modernisation Platform use Auth0 as an authentication mechanism to access various systems. All logs from respective Auth0 tenants are streamed over the Operations Engineering Mod Platform AWS Account.
Activities that count towards user activity include:
Auth0: Authenticating to access enterprise resources via SAML SSO, i.e. Cloud Platform, AWS, or the Analytical Platform’s Control Panel.
GitHub: Creating repositories, pushing to repositories, creating or commenting on issues and pull requests, and various other actions within GitHub.
Why Remove a Dormant GitHub User?
Dormant users can incur unnecessary costs if they hold licenses that could otherwise be allocated to active team members or new users. Additionally, managing dormant users helps maintain security and compliance by reducing the number of potentially inactive accounts that could pose a security risk if compromised.
What’s Required to Remove a Dormant GitHub User?
To remove a dormant GitHub user, you will need:
- Access to GitHub Enterprise: Only enterprise owners or users with sufficient administrative privileges can manage dormant users.
- Permissions to Access AWS S3 and CloudWatch Logs in the operations-engineering-development, mod platform AWS account: The process involves downloading the dormant user report from GitHub, uploading it to an S3 bucket, and querying CloudWatch logs to identify any recent activity outside of GitHub.
- Access to Slack: Notifications of dormant users will be sent to the specified Slack channel (
#operations-engineering-alerts). - Script and GitHub Action Setup: The provided Python script and GitHub action are necessary to automate the identification of dormant users and their removal from GitHub.
Report Dormant GitHub Users to Slack via a GitHub Action
At present, removing a dormant GitHub user is a manual process. The steps to report those users to Slack are performed using a GitHub Action. Follow these steps:
1. Download the Dormant Users Report from GitHub
First, you need to generate and download the dormant user report from GitHub Enterprise (You need to be a GitHub Enterprise Owner to do this). Follow these steps:
- Go to your GitHub Enterprise account.
- Navigate to Your enterprises from your profile menu.
- Select the MOJ enterprise from the list.
- In the sidebar, click Compliance.
- Scroll down to Reports and next to Dormant Users, click New report if a recent report is not already available.
- Once the report is generated, click Download next to the latest dormant users report.
2. Upload the Dormant Users CSV to an S3 Bucket
Once you have downloaded the dormant user report as a CSV file (dormant.csv), upload it to the designated S3 bucket using the AWS CLI.
First, export some short-term credentials from the Operations Engineering Modernisation Platform into your terminal:
export AWS_ACCESS_KEY_ID=<id>
export AWS_SECRET_ACCESS_KEY=<key>
export AWS_SESSION_TOKEN=<session>
Run the following command in your terminal:
aws s3 cp dormant.csv s3://operations-engineering-identify-dormant-users-csv/dormant.csv
This command copies the dormant.csv file from your local system to the S3 bucket operations-engineering-identify-dormant-users-csv.
3. Trigger the GitHub Action Manually
Once the CSV file is uploaded to the S3 bucket, you can manually trigger the GitHub Action to identify dormant users. Here’s how:
- Go to the GitHub repository where the GitHub Action workflow is set up.
- Click on the Actions tab.
- Find the workflow named “Identify Dormant GitHub Users”.
- Click Run workflow to start the process.
4. Review the Workflow Execution
The GitHub Action will perform the following steps:
- Download the
dormant.csvfile from the S3 bucket. - Cross-reference the dormant users list from GitHub with recent auth0 activity logs retrieved from CloudWatch.
- Identify users who are not active in both GitHub organisations or auth0.
- Notify the list of dormant users in the Slack channel
#operations-engineering-alerts.
5. Review and Act on the Slack Notification
Once the workflow is complete, check the #operations-engineering-alerts Slack channel for a notification listing dormant users. Review this list, double-checking the user’s activity in the GitHub UI before removing them from either/both organisations.