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
Loading
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"
AWS services used for this project are:
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:
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