aws-lambda-api-tools 0.1.12 → 0.1.14

package/README.md

@@ -234,12 +234,98 @@ MIT
 
 ## GitHub Actions IAM Setup
 
-This package includes a utility to set up IAM OIDC authentication for GitHub Actions so that you can deploy to AWS from your GitHub Actions:
+This package includes a utility to set up IAM OIDC authentication for GitHub Actions, allowing secure deployments to AWS without storing long-lived credentials.
+
+### Installation
+
+```bash
+npm install aws-lambda-api-tools
+```
+
+### Usage
+
+Create or update an IAM stack for GitHub Actions OIDC authentication:
 
 ```bash
-npx gh-oidc-iam --repo=owner/repo-name [--policy=PolicyName]
+npx aws-lambda-api-tools create-gha-iam-stack --repo=owner/repo-name
 ```
 
-Options:
-- `--repo`: (Required) Your GitHub repository in the format `owner/repo-name`
+### Options
+
+- `--repo`: (Required, Multiple) GitHub repository in the format `owner/repo-name`. Can be specified multiple times to grant access to multiple repositories
 - `--policy`: (Optional) AWS managed policy name to attach to the role. Defaults to 'AdministratorAccess'
+- Uses AWS credentials from your environment or AWS_PROFILE
+
+### Examples
+
+**Single Repository:**
+```bash
+npx aws-lambda-api-tools create-gha-iam-stack --repo=myorg/my-service
+```
+
+**Multiple Repositories:**
+```bash
+npx aws-lambda-api-tools create-gha-iam-stack \
+  --repo=myorg/service-a \
+  --repo=myorg/service-b \
+  --repo=myorg/service-c
+```
+
+**Custom IAM Policy:**
+```bash
+npx aws-lambda-api-tools create-gha-iam-stack \
+  --repo=myorg/my-service \
+  --policy=AWSLambda_FullAccess
+```
+
+**Using AWS Profile:**
+```bash
+AWS_PROFILE=staging npx aws-lambda-api-tools create-gha-iam-stack \
+  --repo=myorg/my-service
+```
+
+### Implementation Details
+
+The tool creates a CloudFormation stack named `GithubActionsIam` containing:
+
+1. An OIDC Provider for GitHub Actions (if it doesn't exist)
+2. An IAM Role with:
+   - Trust policy configured for the specified GitHub repositories
+   - Specified AWS managed policy attached (defaults to AdministratorAccess)
+
+The role ARN is output after stack creation/update and can be used in your GitHub Actions workflows.
+
+### Using in GitHub Actions
+
+Add the following to your GitHub Actions workflow:
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}  # Role ARN from stack output
+          aws-region: us-east-1
+      
+      - name: Deploy
+        run: |
+          # Your deployment steps here
+```
+
+Set the `AWS_ROLE_ARN` secret in your GitHub repository to the role ARN output by the create-gha-iam-stack command.
+
+### Updating Existing Stacks
+
+You can run the command again with different repositories to update the stack:
+- New repositories will be added to the trust policy
+- Existing repositories will remain unchanged
+- The attached policy can be updated by specifying a new --policy value

package/bin/cli.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-"use strict";var o=require("commander"),a=require("path");o.program.name("aws-lambda-api-tools").description("CLI tools for AWS Lambda and API Gateway").version("0.1.5");o.program.command("create-gha-iam-stack").description("Create IAM stack for GitHub Actions OIDC authentication").requiredOption("--repo <owner/repo>","GitHub repository (owner/repo)").option("--policy <name>","AWS managed policy name","AdministratorAccess").action(async r=>{process.argv=[process.argv[0],process.argv[1],`--repo=${r.repo}`,`--policy=${r.policy}`],require((0,a.join)(__dirname,"bootstrap-iam.js"))});o.program.parse();
+"use strict";var o=require("commander"),a=require("path");o.program.name("aws-lambda-api-tools").description("CLI tools for AWS Lambda and API Gateway").version("0.1.5");o.program.command("create-gha-iam-stack").description("Create IAM stack for GitHub Actions OIDC authentication").option("--repo <owner/repo>","GitHub repository (owner/repo)",t,[]).option("--policy <name>","AWS managed policy name","AdministratorAccess").action(async r=>{r.repo.length===0&&(console.error("Error: at least one --repo argument is required"),process.exit(1)),process.argv=[process.argv[0],process.argv[1],...r.repo.map(e=>`--repo=${e}`),`--policy=${r.policy}`],require((0,a.join)(__dirname,"bootstrap-iam.js"))});function t(r,e){return e.concat([r])}o.program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aws-lambda-api-tools",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "",
   "main": "dist/index.js",
   "bin": {