The GitHub Find Inactive Members example script is a handy little script that determines whether a user is still active in an organization by checking the last time each user in an organization performed an action against any of the organization's repositories. If the last action falls before the specified cut-off date, the user is considered inactive and is added to the report. The downside to the script is that it requires Ruby to run, which is something many organization owners are unfamiliar with, and the README.md isn't very Windows-friendly. This guide will outline all the required steps to get the script running on Windows 10.
- Install GitHub Desktop and Clone the Platform-Tools Repository
- Install Ruby for Windows
- Install and Configure Octokit
- Create a Personal Access Token
- Assign the Personal Access Token to an environment variable
- Run the Find Inactive Users Script
First, we'll install GitHub Desktop. Simply download the executable and launch it. The installer will ask if you would like to login to Github.com. Go ahead and login if you like, but it's not essential. If you prefer, you can skip logging in and identify yourself with a name and email address. These are simply metadata fields for the Git client.
Once you've logged in (or chosen not to) and confirmed your details, you'll be presented with the Let's get started! screen.
So let's get started!
Select Clone a repository from the Internet.... As the README.md states, we want to clone https://github.com/github/platform-samples.git. This is simply making a copy of all the files in the github/platform-samples repository, so there will be quite a few scripts we don't necessarily need. These will be fine to delete if you really don't want to keep them.
Once complete, there'll be a Show in Explorer button. Hit that and you'll see all the scripts from the platform-samples repository in the folder, including \api\ruby\find-inactive-members\find_inactive_members.rb.
Head over to RubyInstaller for Windows and hit the red Download button. The next page will present us with a huge list of downloads. If you're unsure, read WHICH VERSION TO DOWNLOAD on the right of the page. At the time of writing, Ruby+Devkit 2.6.X (x64) is the recommended version and is highlighted with => in the list, so let's keep it simple and go with that.
Run the installer, leaving all default options selected. When the initial wizard is complete, you're presented with the following:
Hit the Enter key and let it do its thing, until you hit the next screen:
Hit Enter here as well, and the window will close. Done!
We should now be ready to continue with the steps in the script's README.md.
Open Start Command Prompt with Ruby from the Start Menu.
Open the Command Prompt and navigate to the local folder the repository was cloned to, and run gem install octokit:
As mentioned in the script's README.md, this script will require a Personal access token since it may send quite a few API requests that could exceed the free limit. A personal access token would also be required to report against any private or internal repositories in the organization we have access to view when logged in to GitHub.com.
Navigate to https://github.com/settings/tokens and create a new token called Find Inactive Users (or anything you like) and grant it the repo scope.
Once we choose to generate the token, we are then given the token value in a green box. Be sure to either leave this screen open or save a copy of the token to a file somewhere so you don't lose it. We'll be using it shortly.
If your organization uses Single Sign-on, be sure to Enable SSO using the button on the right.
The script's README.md instructs us to do run export OCTOKIT_ACCESS_TOKEN=00000000000000000000000, replacing 00000000000000000000000 with our personal access token:
We need to change this to setx in order to save it as a persistent environment variable in Windows. To do so, run the following, replacing 00000000000000000000000 with our personal access token:
setx OCTOKIT_ACCESS_TOKEN 00000000000000000000000
Close and re-open the Ruby command prompt and type the following to verify the token is correctly returned:
echo %OCTOKIT_ACCESS_TOKEN%
That's it, we got there! All going well, the script should now work as outlined in the README.md.
In the Ruby command prompt, launch the script with the following command, replacing [org_name] with your organization's name:
ruby find_inactive_members.rb -o [org_name] -d "Jun 15 2020"
It's up to you to decide the date you enter as a threshold to determine whether a user is dormant or not. I ran the really recent date so most, if not all of my organization members would appear for testing purposes.
Once complete, there will be 2 CSV files in the folder the script is located in; inactive_users.csv and unrecognised_authors.csv