GitHub Management Scripts

Keep track of your GitHub Profile and Organizations

Running on AWS, triggered by daily scheduled events,
this project fetches data about the viewer's GitHub Profile and selected Organizations,
compares them to the data stored from the previous run, and emails a diffs report.

  sequenceDiagram
    autonumber
    loop daily
      EventBridge->>Lambda: launches a daily scheduled event
    end
    Lambda->>GitHub: fetches data for creating reports
    Lambda->>S3: fetches previous stored reports
    opt if found diffs
      Lambda-->>S3: store the new reports
      Lambda-->>SES: send an email with a diffs report
    end

Environment variables

The following environment variables are required for runtime:

GITHUB_PAT="your-github-personal-access-token-goes-here"
S3_BUCKET_NAME="name-of-s3-bucket-goes-here"
ORGS_LIST="org-name,another-org-name"
EMAIL_RECIPIENT="email-to-send-notification-to-goes-here"
EMAIL_SENDER="email-to-send-mails-from-goes-here"

Token scopes

• repo
• read:packages
• admin:org
• read:user
• read:discussion
• read:project

Additional environment variables

These, are probably being handled by your local aws-cli or Lambda environment,
nevertheless, if you're running this app without Lambda, you need to set these manually:

AWS_ACCESS_KEY_ID="iam-user-access-key-id-goes-here"
AWS_SECRET_ACCESS_KEY="iam-user-secret-access-key-goes-here"
AWS_REGION="aws-region-goes-here"

Deployment instructions

AWS services used for this project are:

• IAM
• S3
• SES
• Lambda
• CloudWatch
• EventBridge

AWS IAM

• Create a service user and attach the AWSLambda_FullAccess permissions policy to it, take note of the new user's access key id and secret access key. We'll use this user's credentials to deploy Lambda function from the CI workflows.
• Create a Role and attach the following policies to it, AWSLambdaExecute which includes permission to CloudWatch and S3, and the AmazonSESFullAccess (full access is mandatory). We will use this for our Lambda execution for allowing our function to access the rest of the services.

AWS S3

• Create a bucket for storing the previous reports for comparison, it doesn't have to be a public accessible one. and it's up to you if you want to make it preserve versions.

AWS SES

• Configure based on the given instructions, as you see fit, i.e. verify your custom domain and custom from domain if needed.
  Make sure to take you service out of the sandbox environment if you want to able to properly send emails.

AWS Lambda

• Create a function based on the execution IAM Role you created earlier.
• Set the handler to src/main.handler
• Set the timeout to at least a minute, depending on how many items you are fetching.
• Build the project with npm ci
• Upload a Zip archive containing at the following:
  • src/
  • node_modules/
  zip -r github-management-scripts.zip src/ node_modules/
• Publish a new version.
• Create an alias named Live and point it to published version, this will help us maintain versioning for your function, as the triggering event will invoke this alias.
  Note, I like also creating a Dev alias that I use while staging, you can take a look at this project's CI workflows.
• Create the following environment variables for the function's context.
  Note that AWS connection-related variables are being handled by Lambda:
  • GITHUB_PAT token scopes: repo, read:packages, admin:org, read:user, read:discussion, read:project
  • S3_BUCKET_NAME the name of the bucket you created
  • ORGS_LIST comma separated list of organizations you want to track.
  • EMAIL_RECIPIENT where to send the diffs to.
  • EMAIL_SENDER sender email for the diffs email.

Note, this section is hit twice, come back here after the creating the event rule.

AWS CloudWatch

• After the first function invocation, a designated log group will be created, the default retention for it will be *Never Expires*, you can reduce it, 1 week should suffice.

AWS EventBridge

• Create a scheduled rule, for instance 0-10-*-*-?-* will run daily at 10AM.
  Set it to invoke your recently created Lambda function, and select Live as the alias.
  Get back to the Lambda function, and select the new EventBridge rule you created as th trigger.

Run locally

• Create a file named .env at the project's root with the required environment variables
• Install all dependencies with npm install
• Run the application with npm run start:dev