### Example Workflow for Retrieving Secrets

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/api-reference/main-action.md

An example GitHub Actions workflow demonstrating how to use the aws-secretsmanager-get-secrets action. It configures AWS credentials and then calls the action with various inputs for secret retrieval.

```yaml
name: Retrieve Secrets Example

on: push

jobs:
  use-secrets:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-action-role
          aws-region: us-east-1

      - uses: aws-actions/aws-secretsmanager-get-secrets@v3
        with:
          secret-ids: |
            db-password
            MY_API_KEY,api-secret
            prod*
          parse-json-secrets: 'true'
          name-transformation: 'uppercase'
          auto-select-family-attempt-timeout: '2000'

      - run: |
          echo "DB_PASSWORD=$DB_PASSWORD"  # Masked in logs
          echo "MY_API_KEY=$MY_API_KEY"    # Masked in logs
```

--------------------------------

### Example SECRETS_LIST_CLEAN_UP JSON Value

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/configuration.md

This is an example of the JSON string format for the SECRETS_LIST_CLEAN_UP environment variable, which lists the names of environment variables injected by the action.

```json
["DB_PASSWORD", "API_KEY", "CONFIG_HOST"]
```

--------------------------------

### Example Usage of getUserAgent and ACTION_VERSION

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/api-reference/constants.md

Demonstrates how to import and use the `getUserAgent` function and `ACTION_VERSION` constant to construct a custom user agent for the SecretsManagerClient.

```typescript
import { getUserAgent, ACTION_VERSION } from './constants';

const userAgent = getUserAgent();
// Returns: 'github-action/v3.0.0'

const client = new SecretsManagerClient({
  region: process.env.AWS_DEFAULT_REGION,
  customUserAgent: getUserAgent()
});
// AWS API calls will include the user agent in request headers
```

--------------------------------

### No Matching Secrets for Prefix

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/errors.md

Example of using a prefix that does not match any secrets. Verify the prefix in the AWS Console or CLI if this error occurs.

```yaml
- uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: nonexistent*  # No secrets start with 'nonexistent'
```

--------------------------------

### Prefix Search Example

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/README.md

Demonstrates how a prefix search input is translated into an AWS ListSecrets API call and the expected results. This is useful for understanding how to query secrets by name patterns.

```bash
Input: prod*
API Call: ListSecrets(Filters=[{Key: "name", Values: ["prod"]}])
Results: prod-db-pass, prod-api-key, prod-token (max 100)
```

--------------------------------

### Lowercase Name Transformation Example

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/configuration.md

Demonstrates the 'lowercase' transformation for secret names. This is used when the name-transformation input is set to 'lowercase'.

```yaml
- uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: MY-SECRET
    name-transformation: 'lowercase'
  # Creates: my_secret
```

--------------------------------

### Handle Unsupported name-transformation Input

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/errors.md

This example shows how to configure the 'name-transformation' input. The action rejects unsupported transformation names, requiring one of 'uppercase', 'lowercase', or 'none'.

```yaml
- uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: my-secret
    name-transformation: 'camelcase'  # Invalid option
```

--------------------------------

### JSON Parsing Behavior Example

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/README.md

Demonstrates how a JSON secret value is parsed into individual environment variables, including nested keys and values.

```json
Secret: db-creds = {
  "username": "admin",
  "password": "secret",
  "config": {
    "timeout": "30",
    "ssl": true
  }
}

Creates:
DB_CREDS_USERNAME=admin
DB_CREDS_PASSWORD=secret
DB_CREDS_CONFIG_TIMEOUT=30
DB_CREDS_CONFIG_SSL=true
```

--------------------------------

### Invalid Alias Format Example

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/errors.md

Demonstrates invalid and valid alias formats for environment variables. Aliases should only contain uppercase letters, numbers, and underscores.

```yaml
# Invalid aliases:
secret-ids: |
  my-alias,secret      # Lowercase, will become MY_ALIAS after transformation
  my.alias,secret      # Dot is invalid
  123-alias,secret     # Leading digit would be modified

# Valid aliases:
secret-ids: |
  MY_ALIAS,secret
  MY_ALIAS_1,secret
  _ALIAS,secret
```

--------------------------------

### Uppercase Name Transformation Example

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/configuration.md

Demonstrates the default 'uppercase' transformation for secret names. This is used when the name-transformation input is set to 'uppercase' or omitted.

```yaml
- uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: my-secret
    name-transformation: 'uppercase'
  # Creates: MY_SECRET
```

--------------------------------

### Secret Name Transformation Examples

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/README.md

Illustrates how secret names are transformed into valid environment variable names using uppercase transformation, including handling leading digits and invalid characters.

```text
my-secret        → MY_SECRET
test.name        → TEST_NAME
123-start        → _123_START
/prod/db-pass    → _PROD_DB_PASS
MY_SECRET        → MY_SECRET (no change)
```

--------------------------------

### None Name Transformation Example

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/configuration.md

Demonstrates the 'none' transformation, which preserves the original case of secret names. This is used when the name-transformation input is set to 'none'.

```yaml
- uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: My-Secret
    name-transformation: 'none'
  # Creates: My_Secret
```

--------------------------------

### Get Secrets by Prefix

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/README.md

Retrieves all secrets whose names begin with a specified prefix. This is useful for fetching a group of related secrets.

```yaml
- name: Get Secret Names by Prefix
  uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: |
      beta*    # Retrieves all secrets that start with 'beta'
```

--------------------------------

### Environment Variable Name Already in Use Example

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/errors.md

Illustrates a conflict where two secrets would transform into the same environment variable name. Using aliases is recommended to ensure unique names.

```yaml
# This fails if both secrets exist:
secret-ids: |
  MySecret
  mysecret
# Both become: MYSECRET (conflict)

# Solution: use aliases
secret-ids: |
  MY_SECRET_1,MySecret
  MY_SECRET_2,mysecret
```

--------------------------------

### Configure auto-select-family-attempt-timeout in GitHub Actions

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/configuration.md

Examples of how to set the `auto-select-family-attempt-timeout` input in a GitHub Actions workflow. This input specifies the timeout in milliseconds for connecting using the first IP address from a dual-stack DNS lookup.

```yaml
# Default timeout (1 second)
- uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: my-secret
    # auto-select-family-attempt-timeout: '1000' (implicit)
```

```yaml
# Custom timeout for distant regions (2 seconds)
- uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: my-secret
    auto-select-family-attempt-timeout: '2000'
```

```yaml
# Minimum valid timeout (10 ms)
- uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: my-secret
    auto-select-family-attempt-timeout: '10'
```

--------------------------------

### Multiple Secrets with Aliases and No Name Transformation

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/configuration.md

This example retrieves multiple secrets, including those with aliases, and disables name transformation. It's useful when the exact secret name or alias is required.

```yaml
- uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: |
      DATABASE_URL,prod-db-secret
      API_TOKEN,prod-api-secret
      ,prod-config
    parse-json-secrets: 'true'
    name-transformation: 'none'
```

--------------------------------

### Example: Secret Not Found

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/errors.md

This snippet demonstrates how to trigger a 'Secret Not Found' error by providing a non-existent secret ID. Ensure the secret ID is correct and the IAM role has the necessary permissions.

```yaml
- uses: aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: nonexistent-secret  # Secret doesn't exist
```

--------------------------------

### Example Usage of getSecretValue

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/types.md

Demonstrates how to use the getSecretValue function to retrieve a secret and access its name and value. Handles both secret name and ARN inputs.

```typescript
import { getSecretValue, SecretValueResponse } from './utils';

const response: SecretValueResponse = await getSecretValue(client, 'my-secret');

console.log(response.name);          // 'my-secret'
console.log(response.secretValue);   // 'actual-secret-value-or-json'

// When retrieving by ARN
const arnResponse: SecretValueResponse = await getSecretValue(
  client,
  'arn:aws:secretsmanager:us-east-1:123456789012:secret:prod-db-pass-AbCdEf'
);
console.log(arnResponse.name);  // 'prod-db-pass' (extracted from API response)
```

--------------------------------

### Prefix Matches More Than 100 Secrets

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/errors.md

Example of a prefix that matches too many secrets, exceeding the 100-secret limit. Use a more specific prefix or request secrets individually.

```yaml
# If this matches >100 secrets:
secret-ids: a*  # Too many secrets start with 'a'

# More specific:
secret-ids: api-*  # Narrower prefix
```

--------------------------------

### Using Transformation Functions with AWS Secrets Manager Actions

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/types.md

Demonstrates how to use predefined and custom TransformationFunc implementations with utility functions like parseTransformationFunction and transformToValidEnvName. These examples show common use cases for converting secret names into valid environment variable names.

```typescript
import { parseTransformationFunction, transformToValidEnvName } from './utils';

// Using transformation functions returned by parseTransformationFunction
const uppercase = parseTransformationFunction('uppercase');
const lowercase = parseTransformationFunction('lowercase');
const none = parseTransformationFunction('none');

// These are TransformationFunc implementations
uppercase('test-name');    // 'TEST-NAME'
lowercase('TEST-NAME');    // 'test-name'
none('Test-Name');         // 'Test-Name'

// Using TransformationFunc with other utilities
transformToValidEnvName('my-secret', uppercase);  // 'MY_SECRET'
transformToValidEnvName('MY-SECRET', lowercase);  // 'my_secret'
transformToValidEnvName('My-Secret', none);       // 'My_Secret'

// Custom transformation function
const customTransform: TransformationFunc = (input) => `PREFIX_${input.toUpperCase()}`;
transformToValidEnvName('secret', customTransform);  // 'PREFIX_SECRET'
```

--------------------------------

### transformToValidEnvName

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/api-reference/utils.md

Transforms an arbitrary string into a valid Linux/GitHub Actions environment variable name. It handles prepending underscores for names starting with digits, replacing invalid characters, and optional case transformations.

```APIDOC
## transformToValidEnvName

### Description
Transforms an arbitrary string into a valid Linux/GitHub Actions environment variable name. Prepends an underscore if the name starts with a digit, replaces all non-alphanumeric and non-underscore characters with underscores, and optionally applies case transformation.

### Function Signature
```typescript
export function transformToValidEnvName(
  secretName: string,
  nameTransformation?: TransformationFunc,
  hasPrefix?: boolean
): string
```

### Parameters
#### Path Parameters
- **secretName** (string) - Required - String to transform into a valid environment variable name
- **nameTransformation** (TransformationFunc) - Optional - Optional transformation function. If undefined, defaults to uppercase
- **hasPrefix** (boolean) - Optional - If true, skips the leading-digit check. Used internally when building composite names for nested JSON keys

### Returns
- **string** - Transformed string that is a valid environment variable name

### Example
```typescript
import { transformToValidEnvName, parseTransformationFunction } from './utils';

// Default behavior (uppercase)
transformToValidEnvName('my-secret');              // 'MY_SECRET'
transformToValidEnvName('test.name');              // 'TEST_NAME'
transformToValidEnvName('123-start');              // '_123_START' (underscore prepended)

// With custom transformation
const lowercase = parseTransformationFunction('lowercase');
transformToValidEnvName('MY-SECRET', lowercase);   // 'my_secret'

const none = parseTransformationFunction('none');
transformToValidEnvName('My-Secret', none);        // 'My_Secret'

// With hasPrefix=true (skips leading-digit check)
transformToValidEnvName('123-key', undefined, true);  // '123_KEY'
```
```

--------------------------------

### Get Secrets by Name and ARN

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/README.md

Retrieves secrets identified by their names and ARNs, creating environment variables for each. Supports various formats for secret identification, including aliases and comma-separated values.

```yaml
- name: Get secrets by name and by ARN
  uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: |
      exampleSecretName
      arn:aws:secretsmanager:us-east-2:123456789012:secret:test1-a1b2c3
      0/test/secret
      /prod/example/secret
      SECRET_ALIAS_1,test/secret
      SECRET_ALIAS_2,arn:aws:secretsmanager:us-east-2:123456789012:secret:test2-a1b2c3
      ,secret2
```

--------------------------------

### Configure AWS Credentials and Get Secrets

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/configuration.md

This snippet shows the typical workflow of first configuring AWS credentials and then using the aws-secretsmanager-get-secrets action. The AWS_DEFAULT_REGION environment variable is set by the credentials configuration step.

```yaml
- uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::123456789012:role/github-action-role
    aws-region: us-east-1

- uses: aws-actions/aws-secretsmanager-get-secrets@v3
  # AWS_DEFAULT_REGION is now set to 'us-east-1'
```

--------------------------------

### Environment Variable Name Conflicts with CLEANUP_NAME Example

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/errors.md

Shows a scenario where a secret's transformed name conflicts with an internal cleanup variable. An alias must be used to provide a unique name.

```yaml
# This would fail (assuming secret value transforms to SECRETS_LIST_CLEAN_UP):
secret-ids: |
  SECRETS_LIST_CLEAN_UP,my-secret

# Solution: use a different alias
secret-ids: |
  MY_CLEANUP_LIST,my-secret
```

--------------------------------

### Basic Usage of AWS Secrets Manager Get Secrets Action

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/README.md

Add this step to your GitHub Actions workflow to retrieve secrets from AWS Secrets Manager. Configure secret IDs and optional parameters as needed.

```yaml
- name: Step name
  uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: |
      secretId1
      ENV_VAR_NAME, secretId2
    name-transformation: (Optional) uppercase|lowercase|none
    parse-json-secrets: (Optional) true|false
    auto-select-family-attempt-timeout: (Optional) positive integer
```

--------------------------------

### run()

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/INDEX.md

Main entrypoint for the action. Orchestrates the execution of the action's tasks.

```APIDOC
## run()

### Description
Main entrypoint for the action. Orchestrates the execution of the action's tasks.

### Method
N/A (Action Entrypoint)

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### action.yml Cleanup Configuration

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/api-reference/cleanup-action.md

This YAML configuration specifies the main and post-phase entry points for the GitHub Action. The 'post:' directive ensures the cleanup script runs automatically after the main job completes.

```yaml
runs:
  using: 'node24'
  main: 'dist/index.js'
  post: 'dist/cleanup/index.js'
```

--------------------------------

### Alias with Multi-Match Prefix Error

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/errors.md

Illustrates an invalid configuration where an alias is used with a prefix that matches multiple secrets. Aliases require a unique match.

```yaml
# Invalid: alias with multi-match prefix
secret-ids: MY_KEY,prod*  # If prod* matches multiple secrets, fails

# Valid solutions:
secret-ids: |
  MY_KEY,prod-api-key    # Single secret without prefix
  prod-db*               # Prefix without alias
  prod-api*              # More specific prefix matching one secret
```

--------------------------------

### buildSecretsList()

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/INDEX.md

Builds and expands the list of secrets to be retrieved based on the provided configuration.

```APIDOC
## buildSecretsList()

### Description
Builds and expands the list of secrets to be retrieved based on the provided configuration.

### Method
N/A (Internal Function)

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Initialize SecretsManagerClient with Configuration

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/configuration.md

This TypeScript code demonstrates how to initialize the SecretsManagerClient, using the AWS_DEFAULT_REGION environment variable and a custom user agent for request identification.

```typescript
const client = new SecretsManagerClient({
  region: process.env.AWS_DEFAULT_REGION,
  customUserAgent: getUserAgent()
});
```

--------------------------------

### Action Inputs Schema

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/README.md

Defines the input parameters for the AWS Secrets Manager Get Secrets GitHub Action, including secret IDs, JSON parsing options, name transformation, and timeouts.

```yaml
inputs:
  secret-ids:
    description: Secret names, ARNs, or prefixes (one per line)
    required: true
    
  parse-json-secrets:
    description: Parse JSON secrets into individual env vars
    required: false
    default: 'false'
    
  name-transformation:
    description: Case transformation for env var names
    required: false
    default: 'uppercase'
    
  auto-select-family-attempt-timeout:
    description: DNS timeout in milliseconds
    required: false
    default: '1000'
```

--------------------------------

### cleanup

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/api-reference/cleanup-action.md

The main asynchronous function that cleans up environment variables injected by the main action. This function is executed automatically in the `post:` phase of the GitHub Action workflow, after all job steps have completed (whether successful or failed). It reads configuration from environment variables set by the main action.

```APIDOC
## cleanup

### Description
Cleans up environment variables that were injected by the main action. This function is intended to be run in the `post:` phase of a GitHub Actions workflow.

### Function Signature
```typescript
export async function cleanup(): Promise<void>
```

### Parameters
This function does not accept any direct parameters. It reads configuration from environment variables set by the main action.

### Environment Variables Read
- **SECRETS_LIST_CLEAN_UP** (JSON string array) - Required - A JSON-stringified array of environment variable names that were injected and need cleanup.

### Returns
- `Promise<void>`: This function does not return a value upon successful completion.

### Behavior
1. Reads the `SECRETS_LIST_CLEAN_UP` environment variable.
2. If the variable is set and not empty, it parses the JSON array of environment variable names.
3. For each variable name in the list, it attempts to unset the variable using `cleanVariable()`.
4. It verifies that the variable was successfully removed from `process.env` and logs the deletion using `core.debug()`.
5. If a variable still exists after the cleanup attempt, an error is thrown.
6. After all specified variables are cleaned, the `SECRETS_LIST_CLEAN_UP` variable itself is unset.
7. Logs "Cleanup complete" using `core.info()`.
8. Any errors encountered during the process are caught and sent to `core.setFailed()`.

### Throws/Fails Action
- If `SECRETS_LIST_CLEAN_UP` is not set or is empty, cleanup is skipped.
- If `cleanVariable()` fails to remove a variable, an error is thrown with the message: "Failed to clean secret from environment: {variableName}".
- If `JSON.parse()` fails on `SECRETS_LIST_CLEAN_UP`, the error is caught and sent to `core.setFailed()`.
- Any uncaught errors will also be sent to `core.setFailed()`.

### Example
Assume the main action injected the following environment variables:
- `DB_PASSWORD=secret123`
- `API_KEY=apitoken456`
- `CONFIG_HOST=localhost`

The cleanup function, after being invoked, would:
1. Read `SECRETS_LIST_CLEAN_UP = '["DB_PASSWORD", "API_KEY", "CONFIG_HOST"]'`.
2. Call `cleanVariable("DB_PASSWORD")`.
3. Call `cleanVariable("API_KEY")`.
4. Call `cleanVariable("CONFIG_HOST")`.
5. Call `cleanVariable("SECRETS_LIST_CLEAN_UP")`.
6. All these variables would then be unset.
```

--------------------------------

### run

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/api-reference/main-action.md

The main asynchronous function that executes the GitHub Action workflow. It reads action inputs, validates configuration, retrieves secrets from AWS Secrets Manager, transforms secret names into valid environment variable names, and injects them as masked secrets. This function is executed automatically when the action runs.

```APIDOC
## run

### Description
Executes the GitHub Action workflow by retrieving secrets from AWS Secrets Manager and setting them as environment variables.

### Method
Asynchronous function (invoked automatically)

### Parameters
None (reads configuration from GitHub Actions inputs)

### Action Inputs
#### `secret-ids` (string, multiline) - Required
One or more secret names, ARNs, or name prefixes to retrieve, one per line. May include aliases in the format `ALIAS,secretId`. Supports prefix searches with `*` (minimum 3 characters before asterisk).

#### `parse-json-secrets` (boolean) - Optional (Default: 'false')
If 'true', JSON secrets are deserialized and environment variables are created for each key-value pair.

#### `name-transformation` (string) - Optional (Default: 'uppercase')
Transforms environment variable names. Valid values: 'uppercase', 'lowercase', 'none'.

#### `auto-select-family-attempt-timeout` (string, integer) - Optional (Default: '1000')
Timeout in milliseconds for dual-stack DNS first IP connection attempt. Must be >= 10 ms. Used to configure Node.js `setDefaultAutoSelectFamilyAttemptTimeout()`.

### Exported Environment Variable
#### `SECRETS_LIST_CLEAN_UP` (string)
JSON-stringified array of environment variable names that were injected. Used by cleanup action to unset these variables after job completion.

### Throws/Fails Action
- Invalid `auto-select-family-attempt-timeout` (< 10 or NaN): Calls `core.setFailed()` and returns early.
- Invalid `name-transformation` value: `parseTransformationFunction()` throws error, caught at top level.
- Secret retrieval fails (secret not found, access denied, etc.): Logs error with `core.setFailed()` but continues processing other secrets.
- Environment variable name conflict detected during injection: Throws error caught at top level.
- Uncaught error in main try block: Error message sent to `core.setFailed()`.
```

--------------------------------

### Get User Agent for AWS API Calls

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/api-reference/constants.md

Generates a user agent string that identifies requests originating from this GitHub Action. This string is used in AWS API calls for tracking and debugging purposes.

```typescript
export function getUserAgent(): string
```

--------------------------------

### Minimal Configuration for AWS Secrets Manager Get Secrets

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/configuration.md

This snippet demonstrates the most basic configuration, using default values for JSON parsing, name transformation, and timeout. It retrieves a single secret named 'my-secret'.

```yaml
- uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: my-secret
```

--------------------------------

### transformToValidEnvName

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/EXPORTS.md

Transforms an arbitrary string into a valid environment variable name, with an option for case transformation. It can also consider if a prefix is present. It returns the transformed string.

```APIDOC
## transformToValidEnvName

### Description
Transforms arbitrary string into valid environment variable name with optional case transformation.

### Parameters
- **secretName** (string) - Required - The string to transform.
- **nameTransformation** (TransformationFunc) - Optional - The name transformation function to apply.
- **hasPrefix** (boolean) - Optional - Indicates if the original string had a prefix.

### Returns
string - Transformed string suitable for use as environment variable name.
```

--------------------------------

### cleanup()

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/EXPORTS.md

Post-action cleanup function executed after the job completes. Removes environment variables injected by the main action.

```APIDOC
## cleanup()

### Description
Post-action cleanup function executed after the job completes. Removes environment variables injected by the main action.

### Signature
```typescript
export async function cleanup(): Promise<void>
```

### Inputs (via Environment)
- `SECRETS_LIST_CLEAN_UP` (from main action): A list of environment variable names to be cleaned up.

### Behavior
Reads the list of injected variable names from the `SECRETS_LIST_CLEAN_UP` environment variable, unsets each variable, and logs the completion of the cleanup process.

### Error Handling
Uses `core.setFailed()` for errors rather than throwing exceptions.
```

--------------------------------

### Debugging No Matching Secrets

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/errors.md

Command to verify secret names using the AWS CLI when no secrets are found for a given prefix.

```bash
aws secretsmanager list-secrets --filters Key=name,Values=prod-
```

--------------------------------

### Initialize SecretsManagerClient

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/types.md

Creates an instance of the SecretsManagerClient. Specify the AWS region and optionally a custom user agent string for the client.

```typescript
import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';

const client = new SecretsManagerClient({
  region: 'us-east-1',
  customUserAgent: 'github-action/v3.0.0'
});
```

--------------------------------

### Get Secrets with Prefix

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/api-reference/utils.md

Retrieves secret names matching a given prefix from AWS Secrets Manager. Use this when you need to find multiple secrets based on a naming convention. It enforces a maximum of 100 matches per prefix and can optionally require an exact match if an alias is specified.

```typescript
export async function getSecretsWithPrefix(
  client: SecretsManagerClient,
  prefix: string,
  hasAlias: boolean
): Promise<string[]>

```

```typescript
import { getSecretsWithPrefix } from './utils';

const client = new SecretsManagerClient({ region: 'us-east-1' });

const secrets = await getSecretsWithPrefix(client, 'prod-', false);
// Returns: ['prod-db-password', 'prod-api-key', 'prod-token']

// With alias restriction (must match exactly one)
const secret = await getSecretsWithPrefix(client, 'staging-db', true);
// Returns: ['staging-db-password']

```

--------------------------------

### buildSecretsList

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/EXPORTS.md

Builds the final list of secrets by expanding prefixes and deduplicating. It takes an AWS Secrets Manager client, an array of configuration inputs (which can be prefixes or ARNs), and an optional name transformation function. It returns an array of secret IDs or ARNs ready for fetching.

```APIDOC
## buildSecretsList

### Description
Builds final list of secrets by expanding prefixes and deduplicating.

### Parameters
- **client** (SecretsManagerClient) - Required - The AWS Secrets Manager client.
- **configInputs** (string[]) - Required - An array of secret prefixes or ARNs.
- **nameTransformation** (TransformationFunc) - Optional - A function to transform secret names.

### Returns
Promise<string[]> - Array of secret IDs/ARNs ready for fetching.

### Throws
Errors for invalid prefixes, no matches, multi-match with alias, or >100 matches.
```

--------------------------------

### TypeScript Function Signature: buildSecretsList

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/EXPORTS.md

Builds the final list of secrets by expanding prefixes and deduplicating. Returns an array of secret IDs/ARNs ready for fetching. Throws errors for invalid prefixes, no matches, multi-match with alias, or more than 100 matches.

```typescript
export async function buildSecretsList(
  client: SecretsManagerClient,
  configInputs: string[],
  nameTransformation?: TransformationFunc
): Promise<string[]>
```

--------------------------------

### transformToValidEnvName()

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/INDEX.md

Transforms a string into a valid environment variable name.

```APIDOC
## transformToValidEnvName()

### Description
Transforms a string into a valid environment variable name.

### Method
N/A (Utility Function)

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### cleanup()

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/INDEX.md

Performs post-action cleanup tasks, such as removing temporary variables.

```APIDOC
## cleanup()

### Description
Performs post-action cleanup tasks, such as removing temporary variables.

### Method
N/A (Action Entrypoint)

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Transform String to Valid Environment Variable Name

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/api-reference/utils.md

Converts arbitrary strings into valid Linux/GitHub Actions environment variable names. Handles special characters and optional case transformations. Use the `hasPrefix` option to skip the leading-digit check for nested keys.

```typescript
export function transformToValidEnvName(
  secretName: string,
  nameTransformation?: TransformationFunc,
  hasPrefix?: boolean
): string
```

```typescript
import { transformToValidEnvName, parseTransformationFunction } from './utils';

// Default behavior (uppercase)
transformToValidEnvName('my-secret');              // 'MY_SECRET'
transformToValidEnvName('test.name');              // 'TEST_NAME'
transformToValidEnvName('123-start');              // '_123_START' (underscore prepended)

// With custom transformation
const lowercase = parseTransformationFunction('lowercase');
transformToValidEnvName('MY-SECRET', lowercase);   // 'my_secret'

const none = parseTransformationFunction('none');
transformToValidEnvName('My-Secret', none);        // 'My_Secret'

// With hasPrefix=true (skips leading-digit check)
transformToValidEnvName('123-key', undefined, true);  // '123_KEY'
```

--------------------------------

### extractAliasAndSecretIdFromInput()

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/INDEX.md

Extracts the alias and secret ID from the input configuration.

```APIDOC
## extractAliasAndSecretIdFromInput()

### Description
Extracts the alias and secret ID from the input configuration.

### Method
N/A (Internal Function)

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Cleanup Function Signature

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/api-reference/cleanup-action.md

This is the main asynchronous function that handles the cleanup of environment variables. It runs automatically in the 'post:' phase of the GitHub Action workflow.

```typescript
export async function cleanup(): Promise<void>
```

--------------------------------

### Geographically Distant Runner with Extended Timeout

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/configuration.md

This configuration uses a wildcard to fetch secrets and increases the timeout for dual-stack DNS negotiation, which can be helpful for runners in geographically distant regions.

```yaml
- uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: |
      prod*
    auto-select-family-attempt-timeout: '3000'
```

--------------------------------

### Derive Action Version from package.json

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/api-reference/constants.md

Dynamically determines the GitHub Action's semantic version by reading the 'version' field from package.json. The version is prefixed with 'v' to adhere to semantic versioning conventions.

```typescript
const packageJson = require('../package.json');
export const ACTION_VERSION = `v${packageJson.version}`;
```

--------------------------------

### Main Action Function Signature

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/api-reference/main-action.md

The signature for the main asynchronous function that executes the GitHub Action workflow. It reads inputs, retrieves secrets, transforms names, and exports them as masked environment variables.

```typescript
export async function run(): Promise<void>
```

--------------------------------

### JSON Parsing and Lowercase Name Transformation

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/configuration.md

This configuration retrieves multiple secrets ('db-config', 'api-keys') and enables JSON parsing. It also sets the name transformation to 'lowercase' for the retrieved secret names.

```yaml
- uses: aws-actions/aws-secretsmanager-get-secrets@v3
  with:
    secret-ids: |
      db-config
      api-keys
    parse-json-secrets: 'true'
    name-transformation: 'lowercase'
```

--------------------------------

### injectSecret()

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/INDEX.md

Transforms and injects retrieved secrets into the environment.

```APIDOC
## injectSecret()

### Description
Transforms and injects retrieved secrets into the environment.

### Method
N/A (Internal Function)

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### parseTransformationFunction

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/EXPORTS.md

Converts a configuration string into a name transformation function. It supports 'uppercase', 'lowercase', or 'none' modes. It returns the corresponding TransformationFunc.

```APIDOC
## parseTransformationFunction

### Description
Converts configuration string into name transformation function.

### Parameters
- **config** (string) - Required - The configuration string ('uppercase', 'lowercase', or 'none').

### Returns
TransformationFunc - TransformationFunc for the specified mode.

### Throws
Error for unsupported configuration value.
```

--------------------------------

### Set ACTION_VERSION Constant

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/EXPORTS.md

Defines the semantic version of the GitHub Action, dynamically set from package.json. Used by getUserAgent().

```typescript
export const ACTION_VERSION = `v${packageJson.version}`;
```

--------------------------------

### Invalid Prefix Search Patterns

Source: https://github.com/aws-actions/aws-secretsmanager-get-secrets/blob/main/_autodocs/errors.md

Demonstrates invalid and valid patterns for prefix searches in secret IDs. Ensure patterns are at least 3 characters and end with an asterisk.

```yaml
# Invalid patterns:
secret-ids: |
  ab*        # Only 2 characters
  prod       # No asterisk
  prod-?*    # Invalid character '?'

# Valid patterns:
secret-ids: |
  prod*      # OK: 4 characters + *
  my*        # OK: 2 characters + * (actually invalid, need 3 minimum)
  dev-*      # OK: 3 characters + *
```