{"id":43546357,"url":"https://github.com/clear-code/zulip-aws-usage","last_synced_at":"2026-02-03T18:44:39.338Z","repository":{"id":137339940,"uuid":"528387757","full_name":"clear-code/zulip-aws-usage","owner":"clear-code","description":"Programatically send AWS usage report to Zulip.","archived":false,"fork":false,"pushed_at":"2025-04-08T08:58:15.000Z","size":30,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-08T09:46:32.953Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clear-code.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":"2022-08-24T11:13:16.000Z","updated_at":"2025-04-08T08:58:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"d945a369-4d39-4db0-ba07-70b8ec216751","html_url":"https://github.com/clear-code/zulip-aws-usage","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/clear-code/zulip-aws-usage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clear-code%2Fzulip-aws-usage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clear-code%2Fzulip-aws-usage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clear-code%2Fzulip-aws-usage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clear-code%2Fzulip-aws-usage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clear-code","download_url":"https://codeload.github.com/clear-code/zulip-aws-usage/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clear-code%2Fzulip-aws-usage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29053308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T15:43:47.601Z","status":"ssl_error","status_checked_at":"2026-02-03T15:43:46.709Z","response_time":96,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-02-03T18:44:38.510Z","updated_at":"2026-02-03T18:44:39.323Z","avatar_url":"https://github.com/clear-code.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zulip-aws-usage\n\nProgramatically send AWS usage report to Zulip.\n\n## QuickStart\n\n1. Set up an AWS access key.\n\n   * If you don't have `AWS CLI`, then install it.\n      * https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html\n\n   ```console\n   $ aws configure\n   $ cat ~/.aws/credentials\n   [default]\n   aws_access_key_id = xxx\n   aws_secret_access_key = xxx\n   $ cat ~/.aws/config\n   [default]\n   region = ap-northeast-1\n   ```\n\n   * If need, you can use multiple profiles.\n\n   ```console\n   $ aws configure --profile bot\n   $ cat ~/.aws/credentials\n   [default]\n   aws_access_key_id = xxx\n   aws_secret_access_key = xxx\n   [bot]\n   aws_access_key_id = xxx\n   aws_secret_access_key = xxx\n   ```\n\n2. Prepare a bot on Zulip.\n\n   * Visit \"Settings \u003e Personal \u003e Bot\" and create an \"incoming webhook\" bot.\n\n3. Set up your notification configuration.\n\n   ```console\n   $ cp config.yaml.tmpl config.yaml\n   $ vim config.yaml\n   ```\n\n4. Run pip install and run report.py.\n\n   ```console\n   $ python3 -m pip install -r requirments.txt\n   $ python3 report.py\n   ```\n\n   * If you need to use multiple AWS profiles, you can use `--aws-profile` option to specify the profile.\n\n   ```console\n   $ python3 report.py --aws-profile bot\n   ```\n\n## Environmental variables\n\nYou can overwrite each config by the following environmental variables.\n\n|   Env var name   |   Config name    |\n|------------------|------------------|\n| `AWS_ACCOUNT_ID` | `aws.account_id` |\n| `ZULIP_SITE`     | `zulip.site`     |\n| `ZULIP_EMAIL`    | `zulip.email`    |\n| `ZULIP_API_KEY`  | `zulip.api_key`  |\n| `ZULIP_TYPE`     | `zulip.type`     |\n| `ZULIP_TO`       | `zulip.to`       |\n| `ZULIP_TOPIC`    | `zulip.topic`    |\n| `ZULIP_MESSAGE`  | `zulip.message`  |\n\nPlease see `config.yaml.tmpl` for an example value.\n\nYou can run this script without the config file.\nIt would be suitable for CI execution.\n\n## HowTo Guides\n\n### How to send a test message\n\nYou can send reports to yoru private chat by setting `zulip.type` to `private`.\nSee [Zulip API documentation](https://zulip.com/api/send-message) for details.\n\n```yaml\nzulip:\n  ...\n  type: \"private\"\n  to: \"my-name@example.com\"\n  topic: \"\"\n  ...\n```\n\n### How to fix \"Permission denied\" error on AWS\n\nYou need `AWSBudgetsReadOnlyAccess` and ` AmazonEC2ReadOnlyAccess` to fetch the AWS usage data.\n\nCheck your current permission policy on IAM \u003e Users.\n\n### How to schedule bot execution\n\n* systemd\n* GitHub Actions\n\n#### systemd\n\nInstall the service definition files:\n\n```console\n$ mkdir -p ~/.config/systemd/user/\n$ cp systemd/zulip-aws-usage.* ~/.config/systemd/user/\n```\n\nFix the script path or options for the script in `ExecStart`:\n\n```console\n$ vim ~/.config/systemd/user/zulip-aws-usage.service\n```\n\nCheck if the service works:\n\n```console\n$ systemctl start --user zulip-aws-usage.service\n```\n\nIf it worked, enable the timer:\n\n```console\n$ systemctl enable --now --user zulip-aws-usage.timer\n```\n\nYou can check the execution schedule as follows:\n\n```console\n$ systemctl list-timers --user\n```\n\n#### GitHub Actions (Use OpenID Connect)\n\nThis section explains the way to use OpenID Connect without using access keys.\nPlease handle AWS authentication at your own risk, making sure you understand the official documentation beforehand.\n\n1. Set up AWS Identity providers and Roles with reference to the following documents.\n   * [Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services)\n1. Create an empty GitHub repository.\n1. Set each config of this script to GitHub Actions secrets and variables.\n   * Repository variables\n     * `ZULIP_MESSAGE`\n     * `ZULIP_TO`\n     * `ZULIP_TOPIC`\n     * `ZULIP_TYPE`\n   * Secrets variables\n     * `AWS_ACCOUNT_ID`\n     * `ZULIP_API_KEY`\n     * `ZULIP_EMAIL`\n     * `ZULIP_SITE`\n1. Set the role name you set up to secrets so that you can use it on the CI setting.\n   * For example, the name like `AWS_ASSUME_ROLE_NAME`.\n1. Set up GitHub actions to run this script.\n   * Checkout this repository.\n   * Configure AWS Credentials with reference to [Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services).\n     * Use [aws-actions/configure-aws-credentials](https://github.com/aws-actions/configure-aws-credentials).\n   * Run this script with `--use-aws-default-session` option.\n\nExample:\n\n```yaml\nname: Report\non:\n  schedule:\n    - cron: '0 9 * * *'\n  workflow_dispatch:\npermissions:\n  id-token: write\n  contents: read\njobs:\n  report:\n    name: Report\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          repository: clear-code/zulip-aws-usage\n      - name: Configure AWS Credentials\n        uses: aws-actions/configure-aws-credentials@v4\n        with:\n          aws-region: (AWS-REGION)\n          role-to-assume: arn:aws:iam::${{ secrets.AWS_ACCOUNT_ID }}:role/${{ secrets.AWS_ASSUME_ROLE_NAME }}\n      - name: Install requirments\n        run: |\n          pip install -r requirements.txt\n      - name: Report usage\n        run: |\n          python report.py --use-aws-default-session\n        env:\n          AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }}\n          ZULIP_SITE: ${{ secrets.ZULIP_SITE }}\n          ZULIP_EMAIL: ${{ secrets.ZULIP_EMAIL }}\n          ZULIP_API_KEY: ${{ secrets.ZULIP_API_KEY }}\n          ZULIP_TYPE: ${{ vars.ZULIP_TYPE }}\n          ZULIP_TO: ${{ vars.ZULIP_TO }}\n          ZULIP_TOPIC: ${{ vars.ZULIP_TOPIC }}\n          ZULIP_MESSAGE: ${{ vars.ZULIP_MESSAGE }}\n```\n\n## License\n\n```\nCopyright (C) 2022 Daijiro Fukuda \u003cfukuda@clear-code.com\u003e\nCopyright (C) 2022 Fujimoto Seiji \u003cfujimoto@clear-code.com\u003e\n\nThis program is free software; you can redistribute it and/or modify\nit under the terms of the GNU General Public License v2.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclear-code%2Fzulip-aws-usage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclear-code%2Fzulip-aws-usage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclear-code%2Fzulip-aws-usage/lists"}