infrahouse_core package

Subpackages

Submodules

infrahouse_core.exceptions module

Top level exceptions.

The exception hierarchy repeats the structure of the infrahouse_core package. Each module in the package has its own exceptions.py module. The module exceptions are inherited from the upper module exceptions.

exception infrahouse_core.exceptions.IHCoreException[source]

Bases: Exception

Generic InfraHouse Core exception

infrahouse_core.fs module

InfraHouse Toolkit file system module.

infrahouse_core.fs.ensure_permissions(path: str, permissions: int)[source]

For a path on the file system check permissions and set if they differ.

Parameters:

  • path (str) – Filesystem path to a file or directory.

  • permissions (int) – Permissions the file or directory must have. Can be an integer like 0o755 or 0o644.

infrahouse_core.github module

GitHub Actions

class infrahouse_core.github.GitHubActions(github: GitHubAuth, region: str | None = None, role_arn: str | None = None)[source]

Bases: object

The GitHubActions class manages self-hosted GitHub Action runners for an organization.

Parameters:

  • github (GitHubAuth) – GitHub authentication information (token and org).

  • region (str) – AWS region for Secrets Manager operations.

  • role_arn (str) – IAM role ARN to assume for cross-account access.

Example:

auth = GitHubAuth(token="ghp_...", org="my-org")
gha = GitHubActions(auth, region="us-east-1")

# Store a registration token in Secrets Manager
gha.ensure_registration_token("my-runner-token")

# Iterate over runners (lazy — one API page at a time)
for runner in gha.runners:
    print(runner.name, runner.status)

runner = gha.find_runner_by_label("instance_id:i-abc123")
if runner:
    gha.deregister_runner(runner)

# Clean up the token
gha.ensure_registration_token("my-runner-token", present=False)

Note

runners and find_runners_by_label() return iterators, not lists. They fetch subsequent GitHub API pages only as the iterator advances, so memory usage stays bounded to one page (~100 runners) regardless of organization size. This is important in memory-constrained environments such as 128 MB AWS Lambda functions. Callers that need a materialized collection should wrap the result with list().

deregister_runner(runner: GitHubActionsRunner)[source]

De-register a self-hosted runner from the GitHub organization.

Issues DELETE /orgs/{org}/actions/runners/{runner_id} and raises if GitHub returns a non-2xx response. The caller is responsible for stopping the runner process and terminating its host; this method only removes GitHub’s record of the runner.

Parameters:

runner (GitHubActionsRunner) – The runner to de-register.

Raises:

requests.HTTPError – If the GitHub API returns a non-2xx status (for example, 404 if the runner was already removed).

ensure_registration_token(registration_token_secret: str, present=True)[source]

Ensure a registration token is present (by default) or absent in AWS Secrets Manager. If the argument present is true, and the registration token is secret does not exist, it will be created. If the argument present is false, and the registration token is secret exist, it will be deleted.

Parameters:

  • registration_token_secret (str) – The name of the secret to store the token.

  • present (bool) – Whether the registration token should be present or not.

find_runner_by_label(label: str) → GitHubActionsRunner | None[source]

Find the first runner that has the specified label.

Parameters:

label (str) – The label to search for.

Returns:

The first runner matching the label, or None if not found.

Return type:

GitHubActionsRunner or None

find_runners_by_label(label: str) → Iterator[GitHubActionsRunner][source]

Yield all runners that have the specified label.

Iterates lazily over the organization’s runners, fetching subsequent API pages only as the caller advances the iterator. Callers that need a materialized collection should wrap the result with list().

Parameters:

label (str) – The label to search for.

Returns:

An iterator of GitHubActionsRunner objects that match the label.

Return type:

Iterator[GitHubActionsRunner]

property registration_token: str

Request a registration token from GitHub for registering a new runner.

Returns:

A registration token string.

Return type:

str

property runners: Iterator[GitHubActionsRunner]

Iterate over all self-hosted runners for the organization.

Yields runners one at a time, fetching subsequent API pages only as the iterator advances. Keeps memory usage bounded to one page when running in memory-constrained environments (e.g. Lambda).

Each access to this property returns a new independent generator. Iterating it consumes the generator; a second for r in gha.runners loop will replay the GitHub API calls from scratch. If you need to iterate the same set of runners more than once, wrap the first access with list() to materialize the results:

snapshot = list(gha.runners)
busy = [r for r in snapshot if r.busy]
idle = [r for r in snapshot if not r.busy]
Returns:

An iterator of GitHubActionsRunner objects.

Return type:

Iterator[GitHubActionsRunner]

class infrahouse_core.github.GitHubActionsRunner(runner_id: int, github: GitHubAuth, runner_data: dict | None = None)[source]

Bases: object

Represents a GitHub Actions self-hosted runner instance.

Provides access to runner metadata such as status, labels, and instance ID, fetched dynamically via the GitHub API.

property busy: bool

Indicates whether the runner is currently executing a job.

Returns:

True if the runner is busy, False otherwise.

Return type:

bool

property instance_id: str

Extract the EC2 instance ID from the runner’s labels.

Returns:

The instance ID if found, otherwise None.

Return type:

str or None

property labels: List[str]

List all labels assigned to the runner.

Returns:

A list of label names.

Return type:

list[str]

property name: str

Return the name of the runner.

Returns:

Runner name.

Return type:

str

property os: str

Return the operating system of the runner.

Returns:

OS name (e.g., “linux”, “windows”).

Return type:

str

property runner_id: int

Return the runner ID.

Returns:

The ID of the GitHub runner.

Return type:

int

property status: str

Return the runner’s status.

Returns:

Status string (e.g., “online”, “offline”).

Return type:

str

class infrahouse_core.github.GitHubAuth(token: str, org: str)[source]

Bases: object

Authentication information for GitHub API access.

This class holds the necessary credentials to authenticate with the GitHub API. It is used by other classes in this module to make authenticated API calls.

Warning

Tokens should be stored securely (e.g., AWS Secrets Manager). Never log or print the token value. Rotate tokens regularly following your organization’s security policy.

Parameters:

  • token (str) – GitHub Personal Access Token or GitHub App token for authentication. Retrieve from secure storage, never hardcode.

  • org (str) – GitHub organization name where the runners are registered

org: str
token: str
infrahouse_core.github.get_tmp_token(gh_app_id: int, pem_key_secret: str, github_org_name: str, region: str | None = None, role_arn: str | None = None) → str[source]

Generate a temporary GitHub token from GitHUb App PEM key. The GitHub App must be created in your org, can be found in https://github.com/organizations/YOUR_ORG/settings/apps/infrahouse-github-terraform

Parameters:

  • gh_app_id (int) – GitHub Application identifier.

  • pem_key_secret (str) – Secret ARN with the PEM key.

  • github_org_name – GitHub Organization. Used to find GitHub App installation.

  • region (str) – AWS region for Secrets Manager operations.

  • role_arn (str) – IAM role ARN to assume for cross-account access.

Returns:

GitHub token

Return type:

str

infrahouse_core.logging module

InfraHouse Toolkit Logging.

class infrahouse_core.logging.LessThanFilter(exclusive_maximum, name='')[source]

Bases: Filter

Filters out log messages of a lower level.

filter(record)[source]

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

infrahouse_core.logging.setup_logging(logger: Logger | None = None, debug: bool = False, quiet: bool = False, debug_botocore: bool = False) → None[source]

Configure logging for the module.

Sets up stdout/stderr handlers with level-based routing. The logger is configured in place and nothing is returned.

Parameters:

  • logger (logging.Logger or None) – Logger to configure. If None, uses the root logger.

  • debug (bool) – Enable debug logging.

  • quiet (bool) – Suppress INFO logs.

  • debug_botocore (bool) – If True, keep botocore at debug level instead of suppressing it.

infrahouse_core.timeout module

InfraHouse timeout module.

infrahouse_core.timeout.timeout(seconds: int)[source]

Timeout context manager.

Parameters:

seconds (int) – Max execution time in seconds.

Raises:

TimeoutError – when the code under a with is running more than seconds.

infrahouse_core.validation module

Input validation utilities for AWS resource identifiers.

infrahouse_core.validation.validate_dns_name(dns_name: str | None) → None[source]

Validate DNS zone name format.

Parameters:

dns_name (str or None) – DNS name to validate

Raises:

ValueError – If dns_name is invalid

infrahouse_core.validation.validate_instance_id(instance_id: str | None) → None[source]

Validate EC2 instance ID format.

Parameters:

instance_id (str or None) – Instance ID to validate

Raises:

ValueError – If instance_id is invalid

infrahouse_core.validation.validate_region(region: str | None) → None[source]

Validate AWS region name format.

Parameters:

region (str or None) – AWS region name to validate

Raises:

ValueError – If region is invalid

infrahouse_core.validation.validate_role_arn(role_arn: str | None) → None[source]

Validate IAM role ARN format.

Parameters:

role_arn (str or None) – Role ARN to validate

Raises:

ValueError – If role_arn is invalid

infrahouse_core.validation.validate_zone_id(zone_id: str | None) → None[source]

Validate Route53 hosted zone ID format.

Parameters:

zone_id (str or None) – Zone ID to validate

Raises:

ValueError – If zone_id is invalid

Module contents

InfraHouse Core Library.

This library provides reusable classes and functions for AWS and GitHub integration.

Main modules:

  • aws: AWS service integration (EC2, DynamoDB, Secrets Manager, Route53)

  • github: GitHub Actions and API integration

  • logging: Logging configuration utilities

  • timeout: Timeout context manager for operations