.. image:: https://readthedocs.org/projects/simple-gh-aws-creds/badge/?version=latest
:target: https://simple-gh-aws-creds.readthedocs.io/en/latest/
:alt: Documentation Status
.. image:: https://github.com/MacHu-GWU/simple_gh_aws_creds-project/actions/workflows/main.yml/badge.svg
:target: https://github.com/MacHu-GWU/simple_gh_aws_creds-project/actions?query=workflow:CI
.. image:: https://codecov.io/gh/MacHu-GWU/simple_gh_aws_creds-project/branch/main/graph/badge.svg
:target: https://codecov.io/gh/MacHu-GWU/simple_gh_aws_creds-project
.. image:: https://img.shields.io/pypi/v/simple-gh-aws-creds.svg
:target: https://pypi.python.org/pypi/simple-gh-aws-creds
.. image:: https://img.shields.io/pypi/l/simple-gh-aws-creds.svg
:target: https://pypi.python.org/pypi/simple-gh-aws-creds
.. image:: https://img.shields.io/pypi/pyversions/simple-gh-aws-creds.svg
:target: https://pypi.python.org/pypi/simple-gh-aws-creds
.. image:: https://img.shields.io/badge/✍️_Release_History!--None.svg?style=social&logo=github
:target: https://github.com/MacHu-GWU/simple_gh_aws_creds-project/blob/main/release-history.rst
.. image:: https://img.shields.io/badge/⭐_Star_me_on_GitHub!--None.svg?style=social&logo=github
:target: https://github.com/MacHu-GWU/simple_gh_aws_creds-project
------
.. image:: https://img.shields.io/badge/Link-API-blue.svg
:target: https://simple-gh-aws-creds.readthedocs.io/en/latest/py-modindex.html
.. image:: https://img.shields.io/badge/Link-Install-blue.svg
:target: `install`_
.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg
:target: https://github.com/MacHu-GWU/simple_gh_aws_creds-project
.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg
:target: https://github.com/MacHu-GWU/simple_gh_aws_creds-project/issues
.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg
:target: https://github.com/MacHu-GWU/simple_gh_aws_creds-project/issues
.. image:: https://img.shields.io/badge/Link-Download-blue.svg
:target: https://pypi.org/pypi/simple-gh-aws-creds#files
Welcome to ``simple_gh_aws_creds`` Documentation
==============================================================================
.. image:: https://simple-gh-aws-creds.readthedocs.io/en/latest/_static/simple_gh_aws_creds-logo.png
:target: https://simple-gh-aws-creds.readthedocs.io/en/latest/
``simple_gh_aws_creds`` is a Python library that automates the setup of AWS credentials for GitHub Actions workflows. It provides a simple, streamlined approach to grant your GitHub repositories the AWS permissions they need for CI/CD operations.
Overview
------------------------------------------------------------------------------
Using GitHub Actions for CI/CD is incredibly popular in the developer community, and deploying applications to AWS is equally common. But how do you give GitHub Actions the necessary AWS permissions? This library provides a simple, automated solution.
The library automates the complete workflow:
1. **Creates IAM User** - Dedicated user for your GitHub repository
2. **Attaches IAM Policies** - Minimal required permissions (inline + managed policies)
3. **Generates Access Keys** - AWS credentials for authentication
4. **Configures GitHub Secrets** - Automatically uploads credentials to your repository
For cleanup, the process reverses: removes GitHub secrets, deletes access keys, detaches policies, and removes the IAM user.
When to Use This Library
------------------------------------------------------------------------------
**✅ Ideal Use Cases:**
- **Small to Medium Projects** - Perfect for personal projects, prototypes, and small team applications
- **Rapid Development** - Need to quickly set up AWS access without complex configuration
- **Temporary Projects** - Projects with short lifecycles that need quick setup and teardown
- **Learning & Testing** - Educational projects or when experimenting with AWS services
- **Open Source Projects** - Simple automation for contributors without complex OIDC setup
- **Quick Prototyping** - When you need AWS access immediately for proof-of-concepts
**❌ When NOT to Use:**
- **Enterprise Production** - Large-scale production environments with strict security requirements
- **Long-lived Credentials** - If you need credentials that persist for months/years
- **Complex Permission Management** - When you need sophisticated IAM role hierarchies
- **Compliance Requirements** - Environments requiring audit trails, temporary credentials, or specific security standards
- **Multi-Account Strategies** - Complex AWS Organizations with cross-account access patterns
**🏆 Recommended Alternative for Production:**
For enterprise applications, **OIDC (OpenID Connect) with GitHub Actions** is the gold standard. It provides:
- Temporary, short-lived credentials
- No long-lived secrets to manage
- Better audit trails and security
- Fine-grained permission control
However, OIDC setup is more complex and requires deeper AWS knowledge. This library bridges the gap for scenarios where you need quick, automated setup with simpler requirements.
Security Considerations
------------------------------------------------------------------------------
This library trades some security for simplicity and automation:
**Security Features:**
- Principle of least privilege (minimal required permissions)
- Secure credential storage in GitHub Secrets (encrypted at rest)
- Complete cleanup capabilities to prevent credential sprawl
- Automated resource tagging for tracking and management
**Security Trade-offs:**
- Uses long-lived IAM user credentials (less secure than OIDC temporary tokens)
- Stores credentials in GitHub Secrets (still secure, but not as robust as OIDC)
- Simpler setup means less granular control over permissions
Quick Start Example
------------------------------------------------------------------------------
Here's a complete example showing how to set up AWS credentials for your GitHub repository:
.. code-block:: python
# -*- coding: utf-8 -*-
"""
AWS Credentials Setup for GitHub Actions - Complete Example
This script demonstrates how to automatically set up AWS credentials for GitHub Actions
using the simple_gh_aws_creds library. It creates an IAM user with minimal permissions,
generates access keys, and configures GitHub repository secrets.
Prerequisites
------------------------------------------------------------------------------
1. AWS CLI configured with appropriate credentials (or use AWS profile)
2. GitHub personal access token with 'repo' scope permissions
3. Python dependencies installed:
- simple-gh-aws-creds
- boto-session-manager
- home-secret (for secure token management)
What this script does
------------------------------------------------------------------------------
- Creates an IAM user specifically for GitHub Actions
- Attaches minimal IAM permissions (inline policy + optional managed policies)
- Generates AWS access keys and stores them locally
- Configures GitHub repository secrets for CI/CD workflows
- Provides cleanup functionality to remove all resources
Security considerations
------------------------------------------------------------------------------
- Uses principle of least privilege (minimal required permissions)
- Stores credentials securely in GitHub Secrets (encrypted)
- Provides complete cleanup to avoid credential sprawl
- Access keys are long-lived (consider OIDC for production)
Usage
------------------------------------------------------------------------------
1. Customize the configuration parameters below
2. Run setup_all() to create resources
3. Run teardown_all() to clean up everything
4. Switch between setup/teardown by commenting/uncommenting at the bottom
"""
from pathlib import Path
from boto_session_manager import BotoSesManager
from home_secret.api import hs
from simple_gh_aws_creds.api import SetupGitHubRepo
# =============================================================================
# Configuration Parameters - Customize these for your project
# =============================================================================
# AWS region where IAM user will be created and used
# Choose the region closest to your infrastructure or where your main AWS resources are located
aws_region = "us-east-1"
# GitHub repository information
# Replace with your actual GitHub username/organization and repository name
github_user_name = "MacHu-GWU" # Your GitHub username or organization name
github_repo_name = "simple_gh_aws_creds-project" # Your repository name
# Create the SetupGitHubRepo instance with all configuration
setup = SetupGitHubRepo(
# AWS Session Configuration
# BotoSesManager handles AWS authentication - replace profile_name with your AWS profile
# Alternative: Use default credentials, environment variables, or IAM roles
boto_ses=BotoSesManager(
profile_name="bmt_app_dev_us_east_1", # Replace with your AWS CLI profile name
region_name=aws_region,
).boto_ses,
# AWS Region (same as above for consistency)
aws_region=aws_region,
# IAM User Configuration
# This will be the name of the IAM user created for GitHub Actions
# Use a descriptive name that identifies its purpose and project
iam_user_name="gh-ci-simple_gh_aws_creds", # Format: gh-ci-{project-name}
# Resource Tags (for AWS cost tracking and resource management)
# These tags help you identify and manage resources in the AWS console
tags={
"tech:use_case": "for GitHub Action to list Account aliases", # Describe what this user does
"github_user_name": github_user_name, # Link back to GitHub owner
"github_repo_name": github_repo_name, # Link back to GitHub repo
"automation_script": f"https://github.com/{github_user_name}/{github_repo_name}/blob/main/docs/source/01-Examples/setup_dev_account.py",
},
# IAM Inline Policy Document
# Define the minimal permissions needed for your GitHub Actions
# This example allows listing account aliases - customize for your needs
policy_document={
"Version": "2012-10-17", # Current IAM policy version
"Statement": [
{
"Sid": "VisualEditor1", # Statement identifier
"Effect": "Allow", # Grant permission
"Action": [
"iam:ListAccountAliases", # Replace with actions your workflow needs
# Add more actions as needed:
# "s3:GetObject", "s3:PutObject", # For S3 operations
# "lambda:InvokeFunction", # For Lambda operations
# "ssm:GetParameter", # For Parameter Store
],
"Resource": "*", # Scope to specific resources in production
},
],
},
# AWS Managed Policies (optional)
# List of existing AWS managed policy ARNs to attach to the IAM user
# These provide pre-defined permission sets for common use cases
attached_policy_arn_list=[
"arn:aws:iam::aws:policy/IAMReadOnlyAccess", # Example: Read-only IAM access
# Common managed policies you might need:
# "arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess",
# "arn:aws:iam::aws:policy/AWSLambdaExecute",
# "arn:aws:iam::aws:policy/CloudWatchLogsFullAccess",
],
# Local Storage for Access Keys
# File where AWS access keys will be stored locally for reuse
# This file should be added to .gitignore to avoid committing credentials
path_access_key_json=(
Path(__file__).absolute().parent.joinpath("dev_access_key.json")
),
# GitHub Repository Details (repeated for clarity)
github_user_name=github_user_name,
github_repo_name=github_repo_name,
# GitHub Personal Access Token
# This example uses home_secret library for secure token storage
# Alternative methods:
# - Environment variable: os.environ["GITHUB_TOKEN"]
# - Direct string: "ghp_your_token_here" (NOT recommended for production)
# - External secret manager integration
github_token=hs.v("providers.github.accounts.sh.users.sh.secrets.dev.value"),
# GitHub Secrets Configuration
# These are the names that will be used for the GitHub repository secrets
# Your GitHub Actions workflows will use these exact names to access AWS credentials
github_secret_name_aws_default_region="DEV_ACC_AWS_REGION", # AWS region secret name
github_secret_name_aws_access_key_id="DEV_ACC_AWS_ACCESS_KEY_ID", # AWS access key ID secret name
github_secret_name_aws_secret_access_key="DEV_ACC_AWS_SECRET_ACCESS_KEY", # AWS secret key secret name
)
# =============================================================================
# Execution Functions - Choose setup or teardown
# =============================================================================
if __name__ == "__main__":
def setup_all():
"""
Complete setup workflow - Creates all AWS and GitHub resources
This function runs the full setup process in the correct order:
1. Creates IAM user in AWS
2. Attaches IAM policies (inline + managed policies)
3. Generates AWS access keys and stores them locally
4. Configures GitHub repository secrets for CI/CD
Run this function when you want to set up AWS credentials for a new project
or when you need to recreate the credentials from scratch.
Prerequisites:
- AWS credentials configured (CLI profile, environment variables, or IAM role)
- GitHub personal access token with 'repo' scope
- Proper permissions to create IAM users and attach policies
"""
print("🚀 Starting complete AWS credentials setup for GitHub Actions...")
print("=" * 70)
setup.s11_create_iam_user() # Step 1: Create IAM user
setup.s12_put_iam_policy() # Step 2: Attach policies
setup.s13_create_or_get_access_key() # Step 3: Generate access keys
setup.s14_setup_github_secrets() # Step 4: Configure GitHub secrets
print("=" * 70)
print("✅ Setup complete! Your GitHub Actions can now use AWS credentials.")
print(f"🔗 Check your GitHub secrets at: https://github.com/{github_user_name}/{github_repo_name}/settings/secrets/actions")
print("📝 Example GitHub Actions workflow:")
print("""
name: AWS Example
on: [push]
jobs:
aws-job:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
aws-access-key-id: ${{ secrets.DEV_ACC_AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.DEV_ACC_AWS_SECRET_ACCESS_KEY }}
aws-region: ${{ secrets.DEV_ACC_AWS_REGION }}
- name: Test AWS access
run: aws iam list-account-aliases
""")
def teardown_all():
"""
Complete cleanup workflow - Removes all AWS and GitHub resources
This function runs the full cleanup process in the correct order:
1. Removes GitHub repository secrets
2. Deletes AWS access keys
3. Detaches and deletes IAM policies
4. Deletes IAM user
Run this function when you want to:
- Clean up after testing
- Rotate credentials completely
- Decommission a project
- Remove unused credentials for security
⚠️ WARNING: This will permanently delete all AWS credentials and GitHub secrets!
Make sure your GitHub Actions workflows don't depend on these credentials before running.
"""
print("🗑️ Starting complete cleanup of AWS credentials and GitHub secrets...")
print("=" * 70)
setup.s21_delete_github_secrets() # Step 1: Remove GitHub secrets
setup.s22_delete_access_key() # Step 2: Delete AWS access keys
setup.s23_delete_iam_policy() # Step 3: Detach/delete policies
setup.s24_delete_iam_user() # Step 4: Delete IAM user
print("=" * 70)
print("✅ Cleanup complete! All AWS resources and GitHub secrets have been removed.")
print("🔒 Your AWS account is now clean of automation credentials.")
# =============================================================================
# Main Execution - Choose one option below
# =============================================================================
# Option 1: Set up everything (uncomment to run)
setup_all()
# Option 2: Clean up everything (uncomment to run, comment setup_all() above)
# teardown_all()
# Option 3: Run individual steps (for testing or partial operations)
# setup.s11_create_iam_user() # Create just the IAM user
# setup.s12_put_iam_policy() # Attach just the policies
# setup.s13_create_or_get_access_key() # Generate just the access keys
# setup.s14_setup_github_secrets() # Configure just the GitHub secrets
# Individual cleanup steps:
# setup.s21_delete_github_secrets() # Remove just GitHub secrets
# setup.s22_delete_access_key() # Delete just access keys
# setup.s23_delete_iam_policy() # Detach just policies
# setup.s24_delete_iam_user() # Delete just IAM user
The example above demonstrates:
- Complete configuration for a real project
- Minimal IAM permissions (``iam:ListAccountAliases``)
- Optional AWS managed policy attachment
- GitHub secrets configuration
- Both setup and teardown workflows
After running the setup, your GitHub Actions can use the credentials like this:
.. code-block:: yaml
name: AWS Example
on: [push]
jobs:
aws-job:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
aws-access-key-id: ${{ secrets.DEV_ACC_AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.DEV_ACC_AWS_SECRET_ACCESS_KEY }}
aws-region: ${{ secrets.DEV_ACC_AWS_REGION }}
- name: Test AWS access
run: aws iam list-account-aliases
.. _install:
Install
------------------------------------------------------------------------------
``simple_gh_aws_creds`` is released on PyPI, so all you need is to:
.. code-block:: console
$ pip install simple-gh-aws-creds
To upgrade to latest version:
.. code-block:: console
$ pip install --upgrade simple-gh-aws-creds
Raw data
{
"_id": null,
"home_page": null,
"name": "simple-gh-aws-creds",
"maintainer": "Sanhe Hu",
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": "husanhe@email.com",
"keywords": null,
"author": "Sanhe Hu",
"author_email": "husanhe@email.com",
"download_url": "https://files.pythonhosted.org/packages/27/86/6ff2f0bd1796ba5d872fac7da58fe0d0b90ef65826234b2ca8159468bfe3/simple_gh_aws_creds-0.1.1.tar.gz",
"platform": null,
"description": "\n.. image:: https://readthedocs.org/projects/simple-gh-aws-creds/badge/?version=latest\n :target: https://simple-gh-aws-creds.readthedocs.io/en/latest/\n :alt: Documentation Status\n\n.. image:: https://github.com/MacHu-GWU/simple_gh_aws_creds-project/actions/workflows/main.yml/badge.svg\n :target: https://github.com/MacHu-GWU/simple_gh_aws_creds-project/actions?query=workflow:CI\n\n.. image:: https://codecov.io/gh/MacHu-GWU/simple_gh_aws_creds-project/branch/main/graph/badge.svg\n :target: https://codecov.io/gh/MacHu-GWU/simple_gh_aws_creds-project\n\n.. image:: https://img.shields.io/pypi/v/simple-gh-aws-creds.svg\n :target: https://pypi.python.org/pypi/simple-gh-aws-creds\n\n.. image:: https://img.shields.io/pypi/l/simple-gh-aws-creds.svg\n :target: https://pypi.python.org/pypi/simple-gh-aws-creds\n\n.. image:: https://img.shields.io/pypi/pyversions/simple-gh-aws-creds.svg\n :target: https://pypi.python.org/pypi/simple-gh-aws-creds\n\n.. image:: https://img.shields.io/badge/\u270d\ufe0f_Release_History!--None.svg?style=social&logo=github\n :target: https://github.com/MacHu-GWU/simple_gh_aws_creds-project/blob/main/release-history.rst\n\n.. image:: https://img.shields.io/badge/\u2b50_Star_me_on_GitHub!--None.svg?style=social&logo=github\n :target: https://github.com/MacHu-GWU/simple_gh_aws_creds-project\n\n------\n\n.. image:: https://img.shields.io/badge/Link-API-blue.svg\n :target: https://simple-gh-aws-creds.readthedocs.io/en/latest/py-modindex.html\n\n.. image:: https://img.shields.io/badge/Link-Install-blue.svg\n :target: `install`_\n\n.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg\n :target: https://github.com/MacHu-GWU/simple_gh_aws_creds-project\n\n.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg\n :target: https://github.com/MacHu-GWU/simple_gh_aws_creds-project/issues\n\n.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg\n :target: https://github.com/MacHu-GWU/simple_gh_aws_creds-project/issues\n\n.. image:: https://img.shields.io/badge/Link-Download-blue.svg\n :target: https://pypi.org/pypi/simple-gh-aws-creds#files\n\n\nWelcome to ``simple_gh_aws_creds`` Documentation\n==============================================================================\n.. image:: https://simple-gh-aws-creds.readthedocs.io/en/latest/_static/simple_gh_aws_creds-logo.png\n :target: https://simple-gh-aws-creds.readthedocs.io/en/latest/\n\n``simple_gh_aws_creds`` is a Python library that automates the setup of AWS credentials for GitHub Actions workflows. It provides a simple, streamlined approach to grant your GitHub repositories the AWS permissions they need for CI/CD operations.\n\n\nOverview\n------------------------------------------------------------------------------\nUsing GitHub Actions for CI/CD is incredibly popular in the developer community, and deploying applications to AWS is equally common. But how do you give GitHub Actions the necessary AWS permissions? This library provides a simple, automated solution.\n\nThe library automates the complete workflow:\n\n1. **Creates IAM User** - Dedicated user for your GitHub repository\n2. **Attaches IAM Policies** - Minimal required permissions (inline + managed policies)\n3. **Generates Access Keys** - AWS credentials for authentication\n4. **Configures GitHub Secrets** - Automatically uploads credentials to your repository\n\nFor cleanup, the process reverses: removes GitHub secrets, deletes access keys, detaches policies, and removes the IAM user.\n\n\nWhen to Use This Library\n------------------------------------------------------------------------------\n**\u2705 Ideal Use Cases:**\n\n- **Small to Medium Projects** - Perfect for personal projects, prototypes, and small team applications\n- **Rapid Development** - Need to quickly set up AWS access without complex configuration\n- **Temporary Projects** - Projects with short lifecycles that need quick setup and teardown\n- **Learning & Testing** - Educational projects or when experimenting with AWS services\n- **Open Source Projects** - Simple automation for contributors without complex OIDC setup\n- **Quick Prototyping** - When you need AWS access immediately for proof-of-concepts\n\n**\u274c When NOT to Use:**\n\n- **Enterprise Production** - Large-scale production environments with strict security requirements\n- **Long-lived Credentials** - If you need credentials that persist for months/years\n- **Complex Permission Management** - When you need sophisticated IAM role hierarchies\n- **Compliance Requirements** - Environments requiring audit trails, temporary credentials, or specific security standards\n- **Multi-Account Strategies** - Complex AWS Organizations with cross-account access patterns\n\n**\ud83c\udfc6 Recommended Alternative for Production:**\n\nFor enterprise applications, **OIDC (OpenID Connect) with GitHub Actions** is the gold standard. It provides:\n\n- Temporary, short-lived credentials\n- No long-lived secrets to manage\n- Better audit trails and security\n- Fine-grained permission control\n\nHowever, OIDC setup is more complex and requires deeper AWS knowledge. This library bridges the gap for scenarios where you need quick, automated setup with simpler requirements.\n\n\nSecurity Considerations\n------------------------------------------------------------------------------\nThis library trades some security for simplicity and automation:\n\n**Security Features:**\n- Principle of least privilege (minimal required permissions)\n- Secure credential storage in GitHub Secrets (encrypted at rest)\n- Complete cleanup capabilities to prevent credential sprawl\n- Automated resource tagging for tracking and management\n\n**Security Trade-offs:**\n- Uses long-lived IAM user credentials (less secure than OIDC temporary tokens)\n- Stores credentials in GitHub Secrets (still secure, but not as robust as OIDC)\n- Simpler setup means less granular control over permissions\n\n\nQuick Start Example\n------------------------------------------------------------------------------\nHere's a complete example showing how to set up AWS credentials for your GitHub repository:\n\n.. code-block:: python\n\n # -*- coding: utf-8 -*-\n\n \"\"\"\n AWS Credentials Setup for GitHub Actions - Complete Example\n\n This script demonstrates how to automatically set up AWS credentials for GitHub Actions\n using the simple_gh_aws_creds library. It creates an IAM user with minimal permissions,\n generates access keys, and configures GitHub repository secrets.\n\n Prerequisites\n ------------------------------------------------------------------------------\n 1. AWS CLI configured with appropriate credentials (or use AWS profile)\n 2. GitHub personal access token with 'repo' scope permissions\n 3. Python dependencies installed:\n - simple-gh-aws-creds\n - boto-session-manager\n - home-secret (for secure token management)\n\n What this script does\n ------------------------------------------------------------------------------\n - Creates an IAM user specifically for GitHub Actions\n - Attaches minimal IAM permissions (inline policy + optional managed policies)\n - Generates AWS access keys and stores them locally\n - Configures GitHub repository secrets for CI/CD workflows\n - Provides cleanup functionality to remove all resources\n\n Security considerations\n ------------------------------------------------------------------------------\n - Uses principle of least privilege (minimal required permissions)\n - Stores credentials securely in GitHub Secrets (encrypted)\n - Provides complete cleanup to avoid credential sprawl\n - Access keys are long-lived (consider OIDC for production)\n\n Usage\n ------------------------------------------------------------------------------\n 1. Customize the configuration parameters below\n 2. Run setup_all() to create resources\n 3. Run teardown_all() to clean up everything\n 4. Switch between setup/teardown by commenting/uncommenting at the bottom\n \"\"\"\n\n from pathlib import Path\n from boto_session_manager import BotoSesManager\n from home_secret.api import hs\n from simple_gh_aws_creds.api import SetupGitHubRepo\n\n # =============================================================================\n # Configuration Parameters - Customize these for your project\n # =============================================================================\n\n # AWS region where IAM user will be created and used\n # Choose the region closest to your infrastructure or where your main AWS resources are located\n aws_region = \"us-east-1\"\n\n # GitHub repository information\n # Replace with your actual GitHub username/organization and repository name\n github_user_name = \"MacHu-GWU\" # Your GitHub username or organization name\n github_repo_name = \"simple_gh_aws_creds-project\" # Your repository name\n\n # Create the SetupGitHubRepo instance with all configuration\n setup = SetupGitHubRepo(\n # AWS Session Configuration\n # BotoSesManager handles AWS authentication - replace profile_name with your AWS profile\n # Alternative: Use default credentials, environment variables, or IAM roles\n boto_ses=BotoSesManager(\n profile_name=\"bmt_app_dev_us_east_1\", # Replace with your AWS CLI profile name\n region_name=aws_region,\n ).boto_ses,\n\n # AWS Region (same as above for consistency)\n aws_region=aws_region,\n\n # IAM User Configuration\n # This will be the name of the IAM user created for GitHub Actions\n # Use a descriptive name that identifies its purpose and project\n iam_user_name=\"gh-ci-simple_gh_aws_creds\", # Format: gh-ci-{project-name}\n\n # Resource Tags (for AWS cost tracking and resource management)\n # These tags help you identify and manage resources in the AWS console\n tags={\n \"tech:use_case\": \"for GitHub Action to list Account aliases\", # Describe what this user does\n \"github_user_name\": github_user_name, # Link back to GitHub owner\n \"github_repo_name\": github_repo_name, # Link back to GitHub repo\n \"automation_script\": f\"https://github.com/{github_user_name}/{github_repo_name}/blob/main/docs/source/01-Examples/setup_dev_account.py\",\n },\n\n # IAM Inline Policy Document\n # Define the minimal permissions needed for your GitHub Actions\n # This example allows listing account aliases - customize for your needs\n policy_document={\n \"Version\": \"2012-10-17\", # Current IAM policy version\n \"Statement\": [\n {\n \"Sid\": \"VisualEditor1\", # Statement identifier\n \"Effect\": \"Allow\", # Grant permission\n \"Action\": [\n \"iam:ListAccountAliases\", # Replace with actions your workflow needs\n # Add more actions as needed:\n # \"s3:GetObject\", \"s3:PutObject\", # For S3 operations\n # \"lambda:InvokeFunction\", # For Lambda operations\n # \"ssm:GetParameter\", # For Parameter Store\n ],\n \"Resource\": \"*\", # Scope to specific resources in production\n },\n ],\n },\n\n # AWS Managed Policies (optional)\n # List of existing AWS managed policy ARNs to attach to the IAM user\n # These provide pre-defined permission sets for common use cases\n attached_policy_arn_list=[\n \"arn:aws:iam::aws:policy/IAMReadOnlyAccess\", # Example: Read-only IAM access\n # Common managed policies you might need:\n # \"arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess\",\n # \"arn:aws:iam::aws:policy/AWSLambdaExecute\",\n # \"arn:aws:iam::aws:policy/CloudWatchLogsFullAccess\",\n ],\n\n # Local Storage for Access Keys\n # File where AWS access keys will be stored locally for reuse\n # This file should be added to .gitignore to avoid committing credentials\n path_access_key_json=(\n Path(__file__).absolute().parent.joinpath(\"dev_access_key.json\")\n ),\n\n # GitHub Repository Details (repeated for clarity)\n github_user_name=github_user_name,\n github_repo_name=github_repo_name,\n\n # GitHub Personal Access Token\n # This example uses home_secret library for secure token storage\n # Alternative methods:\n # - Environment variable: os.environ[\"GITHUB_TOKEN\"]\n # - Direct string: \"ghp_your_token_here\" (NOT recommended for production)\n # - External secret manager integration\n github_token=hs.v(\"providers.github.accounts.sh.users.sh.secrets.dev.value\"),\n\n # GitHub Secrets Configuration\n # These are the names that will be used for the GitHub repository secrets\n # Your GitHub Actions workflows will use these exact names to access AWS credentials\n github_secret_name_aws_default_region=\"DEV_ACC_AWS_REGION\", # AWS region secret name\n github_secret_name_aws_access_key_id=\"DEV_ACC_AWS_ACCESS_KEY_ID\", # AWS access key ID secret name\n github_secret_name_aws_secret_access_key=\"DEV_ACC_AWS_SECRET_ACCESS_KEY\", # AWS secret key secret name\n )\n\n # =============================================================================\n # Execution Functions - Choose setup or teardown\n # =============================================================================\n\n if __name__ == \"__main__\":\n\n def setup_all():\n \"\"\"\n Complete setup workflow - Creates all AWS and GitHub resources\n\n This function runs the full setup process in the correct order:\n 1. Creates IAM user in AWS\n 2. Attaches IAM policies (inline + managed policies)\n 3. Generates AWS access keys and stores them locally\n 4. Configures GitHub repository secrets for CI/CD\n\n Run this function when you want to set up AWS credentials for a new project\n or when you need to recreate the credentials from scratch.\n\n Prerequisites:\n - AWS credentials configured (CLI profile, environment variables, or IAM role)\n - GitHub personal access token with 'repo' scope\n - Proper permissions to create IAM users and attach policies\n \"\"\"\n print(\"\ud83d\ude80 Starting complete AWS credentials setup for GitHub Actions...\")\n print(\"=\" * 70)\n\n setup.s11_create_iam_user() # Step 1: Create IAM user\n setup.s12_put_iam_policy() # Step 2: Attach policies\n setup.s13_create_or_get_access_key() # Step 3: Generate access keys\n setup.s14_setup_github_secrets() # Step 4: Configure GitHub secrets\n\n print(\"=\" * 70)\n print(\"\u2705 Setup complete! Your GitHub Actions can now use AWS credentials.\")\n print(f\"\ud83d\udd17 Check your GitHub secrets at: https://github.com/{github_user_name}/{github_repo_name}/settings/secrets/actions\")\n print(\"\ud83d\udcdd Example GitHub Actions workflow:\")\n print(\"\"\"\n name: AWS Example\n on: [push]\n jobs:\n aws-job:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - name: Configure AWS credentials\n uses: aws-actions/configure-aws-credentials@v4\n with:\n aws-access-key-id: ${{ secrets.DEV_ACC_AWS_ACCESS_KEY_ID }}\n aws-secret-access-key: ${{ secrets.DEV_ACC_AWS_SECRET_ACCESS_KEY }}\n aws-region: ${{ secrets.DEV_ACC_AWS_REGION }}\n - name: Test AWS access\n run: aws iam list-account-aliases\n \"\"\")\n\n def teardown_all():\n \"\"\"\n Complete cleanup workflow - Removes all AWS and GitHub resources\n\n This function runs the full cleanup process in the correct order:\n 1. Removes GitHub repository secrets\n 2. Deletes AWS access keys\n 3. Detaches and deletes IAM policies\n 4. Deletes IAM user\n\n Run this function when you want to:\n - Clean up after testing\n - Rotate credentials completely\n - Decommission a project\n - Remove unused credentials for security\n\n \u26a0\ufe0f WARNING: This will permanently delete all AWS credentials and GitHub secrets!\n Make sure your GitHub Actions workflows don't depend on these credentials before running.\n \"\"\"\n print(\"\ud83d\uddd1\ufe0f Starting complete cleanup of AWS credentials and GitHub secrets...\")\n print(\"=\" * 70)\n\n setup.s21_delete_github_secrets() # Step 1: Remove GitHub secrets\n setup.s22_delete_access_key() # Step 2: Delete AWS access keys\n setup.s23_delete_iam_policy() # Step 3: Detach/delete policies\n setup.s24_delete_iam_user() # Step 4: Delete IAM user\n\n print(\"=\" * 70)\n print(\"\u2705 Cleanup complete! All AWS resources and GitHub secrets have been removed.\")\n print(\"\ud83d\udd12 Your AWS account is now clean of automation credentials.\")\n\n # =============================================================================\n # Main Execution - Choose one option below\n # =============================================================================\n\n # Option 1: Set up everything (uncomment to run)\n setup_all()\n\n # Option 2: Clean up everything (uncomment to run, comment setup_all() above)\n # teardown_all()\n\n # Option 3: Run individual steps (for testing or partial operations)\n # setup.s11_create_iam_user() # Create just the IAM user\n # setup.s12_put_iam_policy() # Attach just the policies\n # setup.s13_create_or_get_access_key() # Generate just the access keys\n # setup.s14_setup_github_secrets() # Configure just the GitHub secrets\n\n # Individual cleanup steps:\n # setup.s21_delete_github_secrets() # Remove just GitHub secrets\n # setup.s22_delete_access_key() # Delete just access keys\n # setup.s23_delete_iam_policy() # Detach just policies\n # setup.s24_delete_iam_user() # Delete just IAM user\n\n\nThe example above demonstrates:\n\n- Complete configuration for a real project\n- Minimal IAM permissions (``iam:ListAccountAliases``)\n- Optional AWS managed policy attachment\n- GitHub secrets configuration\n- Both setup and teardown workflows\n\nAfter running the setup, your GitHub Actions can use the credentials like this:\n\n.. code-block:: yaml\n\n name: AWS Example\n on: [push]\n jobs:\n aws-job:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - name: Configure AWS credentials\n uses: aws-actions/configure-aws-credentials@v4\n with:\n aws-access-key-id: ${{ secrets.DEV_ACC_AWS_ACCESS_KEY_ID }}\n aws-secret-access-key: ${{ secrets.DEV_ACC_AWS_SECRET_ACCESS_KEY }}\n aws-region: ${{ secrets.DEV_ACC_AWS_REGION }}\n - name: Test AWS access\n run: aws iam list-account-aliases\n\n\n.. _install:\n\nInstall\n------------------------------------------------------------------------------\n\n``simple_gh_aws_creds`` is released on PyPI, so all you need is to:\n\n.. code-block:: console\n\n $ pip install simple-gh-aws-creds\n\nTo upgrade to latest version:\n\n.. code-block:: console\n\n $ pip install --upgrade simple-gh-aws-creds\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple Python library to quickly set up AWS credentials for GitHub Actions without complex OIDC configuration.",
"version": "0.1.1",
"project_urls": {
"Changelog": "https://github.com/MacHu-GWU/simple_gh_aws_creds-project/blob/main/release-history.rst",
"Documentation": "https://simple-gh-aws-creds.readthedocs.io/en/latest/",
"Download": "https://pypi.org/pypi/simple-gh-aws-creds#files",
"Homepage": "https://github.com/MacHu-GWU/simple_gh_aws_creds-project",
"Issues": "https://github.com/MacHu-GWU/simple_gh_aws_creds-project/issues",
"Repository": "https://github.com/MacHu-GWU/simple_gh_aws_creds-project"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ef48ae8c92e20722f3c44676078ff41f8efbcb9dcfdde1c425890ea4a8dbef9b",
"md5": "3508eb1990ac07c6724d566da4ebeef3",
"sha256": "8188f2321bafb73d09199fd587d0415cf51ad56d21dcfa4c6001bc0827d752fc"
},
"downloads": -1,
"filename": "simple_gh_aws_creds-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3508eb1990ac07c6724d566da4ebeef3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 17886,
"upload_time": "2025-07-13T18:48:43",
"upload_time_iso_8601": "2025-07-13T18:48:43.554539Z",
"url": "https://files.pythonhosted.org/packages/ef/48/ae8c92e20722f3c44676078ff41f8efbcb9dcfdde1c425890ea4a8dbef9b/simple_gh_aws_creds-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "27866ff2f0bd1796ba5d872fac7da58fe0d0b90ef65826234b2ca8159468bfe3",
"md5": "712b0850a47bcf885cc8b3df4312b826",
"sha256": "0498c33022c56f41da25fa7ac6e705d86fecbb4e762c1241f31b68f83487a4dc"
},
"downloads": -1,
"filename": "simple_gh_aws_creds-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "712b0850a47bcf885cc8b3df4312b826",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 21333,
"upload_time": "2025-07-13T18:48:44",
"upload_time_iso_8601": "2025-07-13T18:48:44.708939Z",
"url": "https://files.pythonhosted.org/packages/27/86/6ff2f0bd1796ba5d872fac7da58fe0d0b90ef65826234b2ca8159468bfe3/simple_gh_aws_creds-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 18:48:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MacHu-GWU",
"github_project": "simple_gh_aws_creds-project",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "boto3",
"specs": [
[
"==",
"1.39.4"
]
]
},
{
"name": "botocore",
"specs": [
[
"==",
"1.39.4"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2025.1.31"
]
]
},
{
"name": "cffi",
"specs": [
[
"==",
"1.17.1"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.4.1"
]
]
},
{
"name": "cryptography",
"specs": [
[
"==",
"43.0.3"
]
]
},
{
"name": "deprecated",
"specs": [
[
"==",
"1.2.18"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.10"
]
]
},
{
"name": "jmespath",
"specs": [
[
"==",
"1.0.1"
]
]
},
{
"name": "pycparser",
"specs": [
[
"==",
"2.22"
]
]
},
{
"name": "pygithub",
"specs": [
[
"==",
"2.6.1"
]
]
},
{
"name": "pyjwt",
"specs": [
[
"==",
"2.10.1"
]
]
},
{
"name": "pynacl",
"specs": [
[
"==",
"1.5.0"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.9.0.post0"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.3"
]
]
},
{
"name": "s3transfer",
"specs": [
[
"==",
"0.13.0"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.17.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
"==",
"4.13.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"1.26.20"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.3.0"
]
]
},
{
"name": "wrapt",
"specs": [
[
"==",
"1.17.2"
]
]
}
],
"lcname": "simple-gh-aws-creds"
}
JSON
