Metadata-Version: 2.4
Name: simple_gh_aws_creds
Version: 0.2.0
Summary: Create a per-repository AWS IAM user and store its access key as GitHub Actions secrets, with idempotent setup, key rotation, and teardown.
Author-email: Sanhe Hu <husanhe@gmail.com>
Maintainer-email: Sanhe Hu <husanhe@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/MacHu-GWU/simple_gh_aws_creds-project
Project-URL: Documentation, https://simple-gh-aws-creds.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/MacHu-GWU/simple_gh_aws_creds-project
Project-URL: Issues, https://github.com/MacHu-GWU/simple_gh_aws_creds-project/issues
Project-URL: Changelog, https://github.com/MacHu-GWU/simple_gh_aws_creds-project/blob/main/release-history.rst
Project-URL: Download, https://pypi.org/pypi/simple-gh-aws-creds#files
Keywords: aws,iam,github-actions,github-secrets,boto3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <4.0,>=3.11
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
License-File: AUTHORS.rst
Requires-Dist: boto3<2.0.0,>=1.35.0
Requires-Dist: PyGithub<3.0.0,>=2.1.1
Requires-Dist: fire<1.0.0,>=0.7.1
Provides-Extra: dev
Requires-Dist: rich<15.0.0,>=14.3.4; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest<10.0.0,>=9.1.1; extra == "test"
Requires-Dist: pytest-cov<8.0.0,>=7.1.0; extra == "test"
Requires-Dist: moto<6.0.0,>=5.0.0; extra == "test"
Requires-Dist: boto_session_manager<3.0.0,>=2.1.1; extra == "test"
Provides-Extra: doc
Requires-Dist: Sphinx<9.0.0,>=8.2.3; extra == "doc"
Requires-Dist: sphinx-copybutton<1.0.0,>=0.5.2; extra == "doc"
Requires-Dist: sphinx-design<1.0.0,>=0.7.0; extra == "doc"
Requires-Dist: sphinx-jinja<3.0.0,>=2.0.2; extra == "doc"
Requires-Dist: furo==2025.12.19; extra == "doc"
Requires-Dist: pygments<3.0.0,>=2.18.0; extra == "doc"
Requires-Dist: ipython<8.19.0,>=8.18.1; extra == "doc"
Requires-Dist: ipykernel<8.0.0,>=7.3.0; extra == "doc"
Requires-Dist: nbsphinx<1.0.0,>=0.9.8; extra == "doc"
Requires-Dist: rstobj<3.0.0,>=2.0.0; extra == "doc"
Requires-Dist: docfly<4.0.0,>=3.0.3; extra == "doc"
Provides-Extra: mise
Requires-Dist: PyGithub<3.0.0,>=2.8.0; extra == "mise"
Requires-Dist: httpx2<3.0.0,>=2.13.1; extra == "mise"
Dynamic: license-file


.. 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`` gives a GitHub repository its own AWS IAM user, and stores that user's access key as the repository's GitHub Actions secrets. One command sets it up, one command tears it down, and each step is safe to run again.

It fits when you want GitHub Actions to reach AWS in a few minutes, without setting up OIDC:

- open source projects whose CI needs a small, well-scoped piece of AWS;
- test and sandbox accounts, where one IAM user per repository is easy to track;
- a quick start you may later replace with OIDC.

The access key is long-lived. For production accounts, prefer `GitHub OIDC <https://docs.github.com/en/actions/concepts/security/openid-connect>`_.


Quick Start
------------------------------------------------------------------------------
1. Describe the IAM user in a JSON config file:

.. code-block:: json

    {
        "aws_region": "us-east-1",
        "iam_user_name": "gh-ci-my-project",
        "policy_document": {
            "Version": "2012-10-17",
            "Statement": [
                {"Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": "*"}
            ]
        },
        "path_access_key_json": "my_access_key.json",
        "github_user_name": "my-github-user",
        "github_repo_name": "my-project"
    }

2. Create the IAM user, its access key, and the GitHub secrets. AWS credentials come from your AWS profile; the GitHub token from the ``GITHUB_TOKEN`` environment variable:

.. code-block:: bash

    uvx simple-gh-aws-creds setup --config config.json --aws_profile my-profile

3. Use the secrets in a workflow:

.. code-block:: yaml

    jobs:
      aws-job:
        runs-on: ubuntu-latest
        env:
          AWS_DEFAULT_REGION: ${{ secrets.AWS_DEFAULT_REGION }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        steps:
          - run: aws sts get-caller-identity

Read more:

- `Quick Start <https://simple-gh-aws-creds.readthedocs.io/en/latest/01-Quick-Start/index.html>`_: the full walk-through, with prerequisites.
- `How It Works <https://simple-gh-aws-creds.readthedocs.io/en/latest/02-How-It-Works/index.html>`_: what gets created, and the security trade-off.
- `CLI Reference <https://simple-gh-aws-creds.readthedocs.io/en/latest/03-CLI-Reference/index.html>`_: the config file and every command.
- `Python API <https://simple-gh-aws-creds.readthedocs.io/en/latest/04-Python-API/index.html>`_: the same, from Python.
- `Troubleshooting <https://simple-gh-aws-creds.readthedocs.io/en/latest/05-Troubleshooting/index.html>`_: common errors and how to fix them.


.. _install:

Install
------------------------------------------------------------------------------
``simple_gh_aws_creds`` is released on PyPI. Run the command line tool without installing it:

.. code-block:: console

    $ uvx simple-gh-aws-creds --help

Or install it, for the command line tool and the Python API:

.. code-block:: console

    $ pip install simple-gh-aws-creds

To upgrade to latest version:

.. code-block:: console

    $ pip install --upgrade simple-gh-aws-creds


.. _use-with-ai-coding-agents:

Use with AI Coding Agents
------------------------------------------------------------------------------

This repo ships an `Agent Skill <https://code.claude.com/docs/en/skills>`_ that documents the public API of ``simple_gh_aws_creds``, so an AI coding agent such as Claude Code can use the library without reading its source. It lives in `.claude/skills/pypi-simple_gh_aws_creds <https://github.com/MacHu-GWU/simple_gh_aws_creds-project/tree/main/.claude/skills/pypi-simple_gh_aws_creds>`_. To use it in your project, copy it into your project's ``.claude/skills/`` folder. Run this from your project's root:

.. code-block:: console

    $ git clone --depth 1 https://github.com/MacHu-GWU/simple_gh_aws_creds-project.git /tmp/simple_gh_aws_creds-project
    $ mkdir -p .claude/skills
    $ cp -R /tmp/simple_gh_aws_creds-project/.claude/skills/pypi-simple_gh_aws_creds .claude/skills/
