{"id":15140162,"url":"https://github.com/mridang/birdlittle","last_synced_at":"2025-10-23T15:31:49.247Z","repository":{"id":223979252,"uuid":"760954464","full_name":"mridang/birdlittle","owner":"mridang","description":"Birdlittle is Github app acts as a deploy-gate and prevents deploying without workflows passing","archived":false,"fork":false,"pushed_at":"2025-01-18T06:03:08.000Z","size":7337,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-30T19:22:25.251Z","etag":null,"topics":["devex","github","github-app","probot","probot-app"],"latest_commit_sha":null,"homepage":"https://github.com/apps/birdlittle","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mridang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-21T00:53:42.000Z","updated_at":"2025-01-18T06:03:09.000Z","dependencies_parsed_at":"2024-07-17T08:11:54.374Z","dependency_job_id":"54f9d59c-2f32-4851-92a7-44a74814296a","html_url":"https://github.com/mridang/birdlittle","commit_stats":{"total_commits":162,"total_committers":4,"mean_commits":40.5,"dds":0.3641975308641975,"last_synced_commit":"a6d6307666796a9230c0976246f38f1031e3550a"},"previous_names":["mridang/birdlittle"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mridang%2Fbirdlittle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mridang%2Fbirdlittle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mridang%2Fbirdlittle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mridang%2Fbirdlittle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mridang","download_url":"https://codeload.github.com/mridang/birdlittle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237852456,"owners_count":19376687,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["devex","github","github-app","probot","probot-app"],"created_at":"2024-09-26T08:01:31.873Z","updated_at":"2025-10-23T15:31:46.152Z","avatar_url":"https://github.com/mridang.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Birdlittle for GitHub\n\n![Status](https://finch.agarwal.la/version.svg)\n\nBirdlittle is a deployment gate for GitHub Enterprise that\nblocks deploying changes to production if canaries have not passed.\n\nI call it Birdlittle since it was the only name available. There's\na bird in the logo—that should suffice. 😉\n\nBirdlittle is a low-overhead app.\n\n### Installation\n\nFor details about the installation process, see the installation guide.\nThis guide also outlines the reasoning for the necessary scopes.\n\n### Usage\n\nFor details about the usage and associated gotchas, see the installation\nguide.\n\n## Table of Contents\n\n- [Architecture](#architecture)\n- [Developing](#developing)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Architecture\n\nThe app is a NestJS application deployed on AWS Lambda and fronted by\nCloudFront. All SSL certificates are managed automatically via Certificate\nManager (using DNS validation).\n\nTo manage the lock and unlock schedules, EventBridge Scheduler is used\nwhich in turn invokes the Lambda. All credentials are stored in\nSecrets Manager.\n\nThe application uses X-Ray for tracing and Cloudwatch for logging.\n\nThe application is designed to be stateless and does not have any sort\nof persistence—this includes all ephemeral persistence, e.g. caches.\n\n\u003cimg alt=\"Architecture Diagram\" src=\"https://github.com/user-attachments/assets/94f6da8a-7a91-4218-85dd-63c40928a171\"\u003e\n\n## Developing\n\nThe app is built with Typescript 5.3 using the NestJS and requires\nNode 20 to run.\n\nAfter checking out the repository, run `npm install` to install all\nthe required dependencies.\n\nTo develop the application, you must have a GitHub app of your own.\nInstructions on how to create a GitHub app are outside the scope of this\nreadme, but you can find more information here\nhttps://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app\n\nYou must set up a GitHub app prior to proceeding as you will need certain\nsecrets from the app. When setting up the GitHub app, you will be\nprompted to provide the webhook URL and the OAuth callback URL—\nprovide some sample values as these can only be supplied once the app has\nbeen deployed.\n\n### Configure the local environment\n\nConfigure the `.env` file with the necessary information. This file should be set up\nwith example values for a template, but you'll need to replace them with actual data\nrelevant to your application. Here’s a detailed breakdown of each variable:\n\n- `APP_ID`: The unique identifier assigned to your application by GitHub. It's crucial\n  for authenticating your app with the GitHub API.\n\n- `CLIENT_ID`: Used during the OAuth process to initiate user authentication. It's\n  sent to GitHub to receive an authorization code for access token exchange.\n\n- `CLIENT_SECRET`: A sensitive key used alongside the authorization code to securely\n  obtain an access token from GitHub, enabling user-specific data access.\n\n- `WEBHOOK_SECRET`: Ensures the integrity and authenticity of received webhook payloads\n  by validating the signature sent with each event.\n\n- `PRIVATE_KEY`: Allows your app to authenticate directly with the GitHub API for\n  actions or queries under the app's own identity.\n\n- `SENTRY_DSN`: Directs errors and performance data to Sentry for monitoring, aiding in\n  quick identification and resolution of issues.\n\n\u003e [!NOTE]\n\u003e It is fine to add sensitive information to this file as this file only\n\u003e serves as a template and Git has been configured to not track any\n\u003e changes this file using `git update-index --assume-unchanged .env`\n\n---\n\n### Configure the GitHub environment\n\nTo ensure the smooth operation of GitHub Actions within this project, it's\nessential to configure certain environment variables and secrets. These settings\nare crucial for various deployment tasks and integrating with external services\nlike AWS and Sentry.\n\nYou need to set the following environment variables in the GitHub repository\nsettings:\n\n- `AWS_REGION`: The AWS region where your services are deployed, e.g., `us-east-1`.\n- `SENTRY_ORG`: Your organization name in Sentry, e.g., `mridang`, required for Sentry release\n  tracking after deployments.\n- `SENTRY_PROJECT`: The name of your project in Sentry, e.g., `myapp`, required for Sentry release\n  tracking after deployments.\n\nThese variables are used by GitHub Actions workflows to configure the deployment\nenvironment correctly.\n\nAdditionally, you must configure the following secrets in your GitHub repository.\nThese secrets are sensitive and provide access to external services essential for\ndeployments and monitoring:\n\n- `AWS_ACCESS_KEY_ID`: Your AWS access key ID, used by Serverless for deployments.\n- `AWS_SECRET_ACCESS_KEY`: Your AWS secret access key, used by Serverless for deployments.\n- `SENTRY_AUTH_TOKEN`: A Sentry authentication token, required for Sentry release\n  tracking after deployments.\n\nPlease treat these secrets with the utmost care and never expose them publicly.\n\n\u003e [!IMPORTANT]\n\u003e Deployments will not work correctly if these environment variables and secrets\n\u003e are not configured properly. Ensure that you've entered the correct values\n\u003e corresponding to your AWS and Sentry accounts to avoid any deployment issues.\n\n---\n\n### Linting the code\n\nLint the code using `npm run lint`. This command runs ESLint and\nlints all the files. To automatically fix any fixable lint errors, run\n`npm run lint:fix`.\n\n\u003e [!NOTE]\n\u003e GitHub Actions has been configured to automatically fix all fixable\n\u003e lint errors on every commit and commit the changes back to the branch.\n\n### Formatting the code\n\nReformat the code using `npm run format`. This runs Prettier and\nreformats all the code.\n\n\u003e [!NOTE]\n\u003e GitHub Actions has been configured to automatically reformat all the\n\u003e code on every commit and commit the changes back to the branch.\n\n### Deploying the app\n\nThe application is automatically deployed when a push is made to the\ndefault branch. You can manually trigger the deployment workflow if\nyou need to deploy the latest changes.\n\nIt is not recommended to deploy from your local machine but if needed,\nit can be deployed using `npm run deploy`.\n\n\u003e [!IMPORTANT]\n\u003e You'll need to ensure that you have the AWS credentials configured. Read the\n\u003e guide on how to configure the variables https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html\n\nIf you need to package the application without deploying it use\n`npm run package`. This is handy when you need to introspect the contents\nof the ZIP artifact.\n\n### Running tests\n\nRun the test suite using `npm run test`. Most tests are designed to use\nLocalstack when possible. Jest automatically starts the containers defined\nin `docker-compose.yml`.\n\n\u003e [!NOTE]\n\u003e If you run into any issues while running the tests locally, ensure that\n\u003e no other services are currently listening on the same ports used by the\n\u003e services defined in `docker-compose.yml`.\n\u003e Run `docker ps` to list all currently running containers. Any containers\n\u003e listening on the required ports should be stopped prior to running the\n\u003e test suite again.\n\n\u003e On GitHub, these can simply be configured as environment variables\n\u003e https://docs.github.com/en/actions/learn-github-actions/variables\n\nIf configured correctly, you should be able to run all the tests from\nyour IDE.\n\nJest has been configured to automatically collect coverage from tests,\nand these can be found in the `.out` directory.\n\nIf you need to debug hanging tests, you can use `npm run test:debug`\nwhich is handy when the test suite does not exit gracefully or hangs.\n\n### Running the app\n\nTo run the application locally, you can simply run `npx nest start`\nwhich starts the NestJS application for local usage.\n\n\u003e [!IMPORTANT]\n\u003e It is important to keep in mind that the way application runs locally\n\u003e is different from how it runs on Lambda. This is due to shortcomings\n\u003e in the Serverless framework that make emulating a Lambda environment\n\u003e hard.\n\nAssuming that you have followed the instructions and configured\neverything correctly, you should be able to go to\n`http://localhost:3000/health` to see a health-check page that\nreads \"OK\". If you've managed to get here, it indicates that the\napplication has been able to correctly initialize itself.\n\n## Contributing\n\nIf you have suggestions for how this app could be improved, or\nwant to report a bug, open an issue - we'd love all and any\ncontributions.\n\n## License\n\nApache License 2.0 © 2024 Mridang Agarwalla\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmridang%2Fbirdlittle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmridang%2Fbirdlittle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmridang%2Fbirdlittle/lists"}