augint-library 1.3.1

A template library for Python library projects using Poetry and Semantic Release.

Augmenting Integrations Library Template Repository

---

📚 Project Resources

📖 Current Documentation	🧪 Test report for last release

---

Pre-requisites

Install Poetry, AWS CLI, and SAM CLI

Google it and follow the instructions for your platform.

Secret Management

Install chezmoi and age

winget install twpayne.chezmoi
winget install --id FiloSottile.age

Don't forget to setup chezmoi to use age for encryption and github for remote storage.

Set up your AWS OIDC provider (once per account)

Run this once per AWS account (safe to re-run; will no-op if it exists):

aws iam create-open-id-connect-provider `
  --url https://token.actions.githubusercontent.com `
  --client-id-list sts.amazonaws.com

---

⚡ Getting Started

Create a .env file for your repository

# Needed for augint-github to find the repo
GH_REPO=<GITHUB_REPOSITORY>
GH_ACCOUNT=<GITHUB_ACCOUNT>

# Needed to publish to GitHub
GH_TOKEN=<GITHUB_TOKEN>
# Needed for pipeline generate docs stage (module name can't contain dashes)
MODULE_NAME=<MODULE_NAME>
# Needed for pipeline test runners
PYTHON_VERSION=<PYTHON_VERSION>

#######################
# AWS Pipeline Resources
#######################
TESTING_REGION=us-east-1
TESTING_PIPELINE_EXECUTION_ROLE=
TESTING_CLOUDFORMATION_EXECUTION_ROLE=
TESTING_ARTIFACTS_BUCKET=

---

Configure Trusted Publisher on PyPI and TestPyPI

• Go to PyPI Trusted Publishers
• Click Add a trusted publisher, link this repo, and authorize publishing from main
• Repeat on TestPyPI Trusted Publishers for dev

---

Setup your AWS pipeline resources:

1. Create pipeline resources for stages DEV and PROD. Consider stage names like DevApiPortal and ProdApiPortal.

(augint-test-py3.12) PS C:\Users\...\augint-test> sam pipeline bootstrap --stage augint-test-testing

sam pipeline bootstrap generates the required AWS infrastructure resources to connect
to your CI/CD system. This step must be run for each deployment stage in your pipeline,
prior to running the sam pipeline init command.

We will ask for [1] stage definition, [2] account details, and
[3] references to existing resources in order to bootstrap these pipeline resources.

[1] Stage definition
Stage configuration name: augint-test-testing

[2] Account details
The following AWS credential sources are available to use.
To know more about configuration AWS credentials, visit the link below:
https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html
     1 - Environment variables (not available)
     2 - default (named profile)
     3 - ...
     q - Quit and configure AWS credentials
Select a credential source to associate with this stage: 2
Associated account XYZ with configuration augint-test-testing.

Enter the region in which you want these resources to be created [us-east-1]:
Select a user permissions provider:
     1 - IAM (default)
     2 - OpenID Connect (OIDC)
Choice (1, 2): 2
Select an OIDC provider:
     1 - GitHub Actions
     2 - GitLab
     3 - Bitbucket
Choice (1, 2, 3): 1
Enter the URL of the OIDC provider [https://token.actions.githubusercontent.com]:
Enter the OIDC client ID (sometimes called audience) [sts.amazonaws.com]:
Enter the GitHub organization that the code repository belongs to. If there is no organization enter your username instead: svange
Enter GitHub repository name: augint-test
Enter the name of the branch that deployments will occur from [main]:

...
Press enter to confirm the values above, or select an item to edit the value:

Fix the trust policy on the generated PipelineExecutionRole

SAM CLI generates an invalid trust policy (uses ForAllValues:StringLike which fails). Run this after bootstrap:

# Load environment variables from .env file
get-content .env | foreach {
    $name, $value = $_.split('=')
    if ([string]::IsNullOrWhiteSpace($name) -or $name.Contains('#')) {
        # skip empty or comment line in ENV file
        return
    }
    set-content env:\$name $value
}

# Get AWS account ID
$accountId = (aws sts get-caller-identity --query 'Account' --output text)
# Set your GitHub org/user and repo
$githubUserOrOrg = $env:GH_ACCOUNT  
$githubRepo = $env:GH_REPO
$projectPrefix = ($githubRepo.Substring(0, [Math]::Min(9, $githubRepo.Length)))  # first 9 chars

echo "Project prefix: $projectPrefix"
echo "GitHub User/Org: $githubUserOrOrg"
echo "GitHub Repo: $githubRepo"


# Find the generated pipeline execution role
$roleName = aws iam list-roles `
  --query "Roles[?starts_with(RoleName, 'aws-sam-cli-managed-${projectPrefix}') && contains(RoleName, 'PipelineExecutionRole')].RoleName" `
  --output text

if (-not $roleName) {
    Write-Error "Could not find a PipelineExecutionRole for project prefix $projectPrefix"
    exit 1
}

# Define the trust policy
$trustPolicy = @"
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::${accountId}:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": [
            "repo:${githubUserOrOrg}/${githubRepo}:ref:refs/heads/fix/*",
            "repo:${githubUserOrOrg}/${githubRepo}:ref:refs/heads/feat/*",
            "repo:${githubUserOrOrg}/${githubRepo}:ref:refs/heads/dev",
            "repo:${githubUserOrOrg}/${githubRepo}:ref:refs/heads/main"
          ]
        }
      }
    }
  ]
}

"@

echo "Updating trust policy for role: $roleName"
echo "Trust policy: $trustPolicy"

# Update the role trust policy
aws iam update-assume-role-policy `
  --role-name $roleName `
  --policy-document $trustPolicy

Save your .env file

$githubRepo = $env:GH_REPO
chezmoi add .env
chezmoi git add .
chezmoi git commit -- -am "Add .env file for $githubRepo"

Enable pre-commit hooks

pre-commit install
pre-commit install --install-hooks
pre-commit run --all-files

---

---

Change augint-library to your project name:

• in pyproject.toml also, change the version to 0.0.0
• in .github/workflows/pipeline.yaml
• in README.md
• Rename directory: src/augint_test → src/<your_project_name>
• Clear contents of CHANGELOG.md

---

Push the .env file vars and secrets to your repository

ai-gh-push

Fix up your poetry lock file:

poetry install
poetry lock

Finally, push your repo! Don't for get to set your repository's branch protection rules to require a successful run of the pipeline before merging PRs.

---

Helpful Commands

# "source" an .env file in PowerShell
get-content .env | foreach {
    $name, $value = $_.split('=')
    if ([string]::IsNullOrWhiteSpace($name) -or $name.Contains('#')) {
        # skip empty or comment line in ENV file
        return
    }
    set-content env:\$name $value
}