{"id":16476421,"url":"https://github.com/softprops/aws-credential-rotary","last_synced_at":"2025-03-23T11:32:59.932Z","repository":{"id":47750821,"uuid":"294002740","full_name":"softprops/aws-credential-rotary","owner":"softprops","description":null,"archived":false,"fork":false,"pushed_at":"2023-05-04T19:41:36.000Z","size":1666,"stargazers_count":9,"open_issues_count":6,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-17T11:59:49.076Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/softprops.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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},"funding":{"ko_fi":"softprops"}},"created_at":"2020-09-09T04:31:08.000Z","updated_at":"2024-09-13T01:05:01.000Z","dependencies_parsed_at":"2024-10-11T12:42:29.363Z","dependency_job_id":"53cb315e-16d4-4b13-a3ce-6128c5eeed89","html_url":"https://github.com/softprops/aws-credential-rotary","commit_stats":{"total_commits":58,"total_committers":3,"mean_commits":"19.333333333333332","dds":"0.051724137931034475","last_synced_commit":"ff295d91be23e9e111d627d7971b4839a71442d2"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Faws-credential-rotary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Faws-credential-rotary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Faws-credential-rotary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softprops%2Faws-credential-rotary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softprops","download_url":"https://codeload.github.com/softprops/aws-credential-rotary/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245097158,"owners_count":20560311,"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":[],"created_at":"2024-10-11T12:42:27.689Z","updated_at":"2025-03-23T11:32:59.471Z","avatar_url":"https://github.com/softprops.png","language":"TypeScript","funding_links":["https://ko-fi.com/softprops"],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  🔄\n  \u003cbr/\u003e\n  AWS Credential Rotary\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n   A GitHub action for rotating AWS credentials stored in GitHub secrets\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/softprops/aws-credential-rotary/actions\"\u003e\n\t\t\u003cimg src=\"https://github.com/softprops/aws-credential-rotary/workflows/Main/badge.svg\"/\u003e\n\t\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n## 🤔 why bother\n\nAWS assumes a shared security responsibility model with you and it's services.\n\nIt goes to great lengths to secure your privacy and access to services which your users depend on.\nIt also assumes that you are doing the same with the credentials that permit access to those services and data.\nAWS [documents some helpful best practices](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html) to manage that.\n\nOne of those practices is ensuring you are periodically rotating your credentials. The longer lived your credentials are, the greater the opportunity of inviting unwanted and unintential breach of your aws managed systems and data is.\n\nIn short, it is much easier to rotate your credentials than to cope with the aftermath of a data access breach.\n\n## 🤸 usage\n\nThis action depends on the ability to update repository secrets. As such it requires an GitHub api token with `repo` permissions.\n\nCreate a personal access token with `repo` permissions on [github.com](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) or if you prefer the command line, [try octopat](https://github.com/softprops/octopat). If you intend to update organization wide secrets, the access token must have `admin:org` permissions.\n\nStore that access token in your [GitHub repository secrets](https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets), then provide that as `GITHUB_TOKEN` environment variable to the GitHub action step for aws-credential-rotary.\n\nThis action also depends on having the ability to list, create, and delete iam access keys.\n\nThe IAM Statement permitting this permissions should look something like the following\n\n```json\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Action\": [\n        \"iam:ListAccessKeys\",\n        \"iam:CreateAccessKey\",\n        \"iam:DeleteAccessKey\",\n        \"sts:GetCallerIdentity\"\n      ],\n      \"Resource\": \"arn:aws:iam::*:user/*\",\n      \"Effect\": \"Allow\"\n    }\n  ]\n}\n```\n\nBy default, this action assumes the credentials used to rotate are the same as the iam user for other GitHub action scontinuous integration and deployment operations.\n\nThe example below rotates credentials just before they are used\n\n```diff\nname: Main\n\non: push\n\njobs:\n  main:\n    runs-on: ubuntu-latest\n    steps:\n+     - name: Rotate credentials\n+       uses: softprops/aws-credential-rotary@v1\n+       env:\n+         GITHUB_TOKEN: ${{ secrets.REPO_GITHUB_TOKEN }}\n+         AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}\n+         AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n      - name: Print Create Date\n        run: aws iam list-access-keys --user name-of-iam-user-associated-with-credentials --query 'AccessKeyMetadata[0].CreateDate' --output text\n        env:\n          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}\n          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n          AWS_REGION: us-east-1\n```\n\n### Rotating on a schedule\n\nIt is recommended to rotate credentials on a [schedule](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#scheduled-events). You can find some [example schedules here](https://crontab.guru/examples.html)\n\n```diff\nname: Rotate AWS Credentials\n\n+ on:\n+  schedule:\n+    # At 00:00 on Sunday.\n+    - cron:  '0 0 * * 0'\n\njobs:\n  main:\n    runs-on: ubuntu-latest\n    steps:\n     - name: Rotate credentials\n       uses: softprops/aws-credential-rotary@v1\n       env:\n         GITHUB_TOKEN: ${{ secrets.REPO_GITHUB_TOKEN }}\n         AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}\n         AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n      - name: Print Create Date\n        run: aws iam list-access-keys --user name-of-iam-user-associated-with-credentials --query 'AccessKeyMetadata[0].CreateDate' --output text\n        env:\n          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}\n          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n          AWS_REGION: us-east-1\n```\n\n### Specifying IAM username\n\nWhen the IAM user associated with for the credentials to be rotated is not the same as the IAM user used to rotate credentials, you can specify an `iam-user-name` for disambiguating the two.\n\n```diff\nname: Main\n\non: push\n\njobs:\n  main:\n    runs-on: ubuntu-latest\n    steps:\n     - name: Rotate credentials\n       uses: softprops/aws-credential-rotary@v1\n+       with:\n+           iam-user-name: 'name-of-iam-user-associated-with-credentials'\n       env:\n         GITHUB_TOKEN: ${{ secrets.REPO_GITHUB_TOKEN }}\n         AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}\n         AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n      - name: Print Create Date\n        run: aws iam list-access-keys --user name-of-iam-user-associated-with-credentials --query 'AccessKeyMetadata[0].CreateDate' --output text\n        env:\n          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}\n          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n          AWS_REGION: us-east-1\n```\n\n### Specifying AWS_REGION\n\nThis action uses the aws v3 sdk which [requires a region to be provided](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-region.html). If you do not provide one via an `AWS_REGION` env variable `us-east-1` is assumed\n\n```diff\nname: Main\n\non: push\n\njobs:\n  main:\n    runs-on: ubuntu-latest\n    steps:\n     - name: Rotate credentials\n       uses: softprops/aws-credential-rotary@v1\n       env:\n         GITHUB_TOKEN: ${{ secrets.REPO_GITHUB_TOKEN }}\n         AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}\n         AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n+        AWS_REGION: 'us-west-2'\n      - name: Print Create Date\n        run: aws iam list-access-keys --user name-of-iam-user-associated-with-credentials --query 'AccessKeyMetadata[0].CreateDate' --output text\n        env:\n          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}\n          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n          AWS_REGION: us-east-1\n```\n\n### Custom secret names\n\nBy default, this action will assume the credentials to be rotated exist as secrets named `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. You can override these with the following inputs\n\n```diff\nname: Main\n\non: push\n\njobs:\n  main:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Rotate credentials\n        uses: softprops/aws-credential-rotary@v1\n        with:\n            iam-user-name: 'name-of-iam-user-associated-with-credentials'\n+           github-access-key-id-name: 'CUSTOM_ACCESS_KEY_ID_NAME'\n+           github-secret-access-key-name: 'CUSTOM_SECRET_ACCESS_KEY_NAME'\n        env:\n          GITHUB_TOKEN: ${{ secrets.REPO_GITHUB_TOKEN }}\n          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}\n          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n      - name: Print Create Date\n        run: aws iam list-access-keys --user name-of-iam-user-associated-with-credentials --query 'AccessKeyMetadata[0].CreateDate' --output text\n        env:\n          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}\n          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n          AWS_REGION: us-east-1\n```\n\n### Rotating repository's environment secrets\n\nIf you utilise the repository [environment](https://docs.github.com/en/actions/reference/environments) protection rules, you can specify the `environment` input parameter. Only the secrets from the repository's environment will be updated.\n\n```diff\nname: Rotate environment secrets\n\non: push\n\njobs:\n  main:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Rotate credentials\n        uses: softprops/aws-credential-rotary@v1\n        with:\n+           environment: 'sandbox'\n        ...\n```\n\n### Rotating organization secrets\n\nIf you specify the `organization` input parameter, the secrets from this organization will be updated instead of the secrets of the current repository.\n\n```diff\nname: Rotate organization secrets\n\non: push\n\njobs:\n  main:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Rotate credentials\n        uses: softprops/aws-credential-rotary@v1\n        with:\n+           organization: 'name-of-the-github-organization'\n        ...\n```\n\n\u003e :warning: Do **NOT** set both `organization` and `environment` parameters.  \nIf you do, the script will prioritise the `organization` parameter and ignore the `environment` parameter.\n\n### Rotating multiple keys\n\nMonorepos which deploy multiple aws services may use multiple sets of aws credentials to do so. You can simply add multiple aws credential rotary steps\n\n```diff\nname: Rotate Multiple AWS Credentials\n\non:\n schedule:\n   # At 00:00 on Sunday.\n   - cron:  '0 0 * * 0'\n\n\njobs:\n  main:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Rotate service a credentials\n        uses: softprops/aws-credential-rotary@v1\n        with:\n           github-access-key-id-name: 'SERVICE_A_AWS_ACCESS_KEY_ID'\n           github-secret-access-key-name: 'SERVICE_A_AWS_SECRET_ACCESS_KEY'\n        env:\n          GITHUB_TOKEN: ${{ secrets.REPO_GITHUB_TOKEN }}\n          AWS_ACCESS_KEY_ID: ${{ secrets.SERVICE_A_AWS_ACCESS_KEY_ID }}\n          AWS_SECRET_ACCESS_KEY: ${{ secrets.SERVICE_A_AWS_SECRET_ACCESS_KEY }}\n      - name: Rotate service b credentials\n        uses: softprops/aws-credential-rotary@v1\n        with:\n           github-access-key-id-name: 'SERVICE_B_AWS_ACCESS_KEY_ID'\n           github-secret-access-key-name: 'SERVICE_B_AWS_SECRET_ACCESS_KEY'\n        env:\n          GITHUB_TOKEN: ${{ secrets.REPO_GITHUB_TOKEN }}\n          AWS_ACCESS_KEY_ID: ${{ secrets.SERVICE_B_AWS_ACCESS_KEY_ID }}\n          AWS_SECRET_ACCESS_KEY: ${{ secrets.SERVICE_B_AWS_SECRET_ACCESS_KEY }}\n```\n\n### Special note\n\nGitHub actions workflows can be triggered asynchonously. Without coordination you can run into a case where two workflows triggered independently try to create/delete credentials at the same time. When you trigger your rotation workflow on a schedule it's unlikely this will happen. If you trigger your workflow on a push or other means we recommend serializing your workflow runs with an action like [Turnstyle](https://github.com/softprops/turnstyle)\n\n## inputs\n\n| Name                            | Type   | Description                                                                                                       |\n| ------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |\n| `iam-user-name`                 | string | AWS IAM username associated with credentials to be rotated. Defaults to sts get-caller-identity infered user name |\n| `github-access-key-id-name`     | string | GitHub secret name used to store AWS access key id. Defaults to AWS_ACCESS_KEY_ID                                 |\n| `github-secret-access-key-name` | string | GitHub secret name used to store AWS access key secret. Defaults to AWS_SECRET_ACCESS_KEY                         |\n| `organization`                  | string | If specified, the secret of this organization will be rotated instead of the one from the current repository      |\n\nDoug Tangren (softprops) 2020.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftprops%2Faws-credential-rotary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftprops%2Faws-credential-rotary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftprops%2Faws-credential-rotary/lists"}