githubRole

GitHub Actions IAM roles enable secure deployment from GitHub workflows to AWS without storing long-term credentials. Using OpenID Connect (OIDC), GitHub Actions can assume AWS IAM roles with fine-grained permissions and repository-scoped access controls.

import * as saws from "@stackattack/aws";

const ctx = saws.context();
const deploymentRole = saws.githubRole(ctx, {
  repo: "myorg/myapp",
  policy: JSON.stringify({
    Version: "2012-10-17",
    Statement: [{
      Effect: "Allow",
      Action: "s3:*",
      Resource: "*"
    }]
  })
});

export const roleArn = deploymentRole.arn;

Usage

In your GitHub Actions workflow, configure the role assumption:

name: Deploy
on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/my-github-role
          role-session-name: GitHubActions
          aws-region: us-east-1
      - run: aws s3 ls  # Now authenticated with AWS

Costs

GitHub Actions OIDC integration has no additional AWS costs beyond standard IAM usage:

• IAM roles and policies: Free (no charges for creation or storage)
• STS AssumeRole calls: $0.01 per 1,000 requests (typically negligible)
• Resource usage: Costs depend on what AWS services the role accesses

This approach eliminates the security risks and management overhead of storing AWS access keys as GitHub secrets, making it both more secure and cost-effective than alternatives.

githubRole

Creates an IAM role that can be assumed by GitHub Actions workflows via OIDC.

function githubRole(ctx: Context, args: GithubRoleArgs): Role

Parameters

• ctx (Context) - The context for resource naming and tagging
• args (GithubRoleArgs) - Configuration arguments for the GitHub role

Returns

• (Role) - Creates an IAM role that can be assumed by GitHub Actions workflows via OIDC.

Functions

githubAssumeRolePolicy

Creates an IAM policy document that allows GitHub Actions to assume a role via OIDC.

function githubAssumeRolePolicy(args: GithubAssumeRolePolicyArgs): Output<GetPolicyDocumentResult>

Parameters

• args (GithubAssumeRolePolicyArgs) - Configuration for the assume role policy

Returns

• (Output<GetPolicyDocumentResult>) - Creates an IAM policy document that allows GitHub Actions to assume a role via OIDC.

Interfaces

GithubAssumeRolePolicyArgs

Configuration arguments for creating a GitHub assume role policy.

Properties

• openIdProvider (Input<string>) - ARN of the OpenID Connect provider for GitHub Actions
• repo (Input<string>) - GitHub repository in the format “owner/repo”
• scope? (Input<string>) - Optional scope to restrict access (e.g., “ref:refs/heads/main”, defaults to ”*“)

GithubRoleArgs

Configuration arguments for creating a GitHub Actions IAM role.

Properties

• noPrefix? (boolean) - Whether to skip adding a prefix to the resource name
• openIdProvider? (null | Input<string>) - ARN of existing OpenID Connect provider (creates new one if not provided). If not passed, a provider will be created. If you pass null, an existing OpenID Connect provider for https://token.actions.githubusercontent.com will be looked up in your AWS account
• policy? (Input<string>) - Optional inline policy to attach to the role
• repo (Input<string>) - GitHub repository in the format “owner/repo”
• scope? (Input<string>) - Optional scope to restrict access (e.g., “ref:refs/heads/main”, defaults to ”*”)