CloudFormation Parameters Reader

            

A GitHub Action that reads CloudFormation deployment parameters from a JSON artifact file and makes them available as outputs and environment variables for use in subsequent workflow steps.

Overview

This action simplifies CloudFormation deployments by standardizing how parameters are extracted from configuration files. It parses a JSON artifact file containing CloudFormation deployment configuration and exposes the parameters, stack name, and template path as both GitHub Actions outputs and environment variables.

Features

• 📄 Reads deployment configuration from a JSON artifact file
• 🔍 Extracts CloudFormation parameters, stack name, and template path
• 🔌 Provides values as both GitHub Actions outputs and environment variables
• ⚠️ Handles errors gracefully with clear error messages
• 📝 Logs extracted values for easy debugging

Inputs

Name	Description	Required	Default
artifact-path	Path to the deployment.json artifact file	No	./artifacts/deployment.json

Outputs

Name	Description
parameters	CloudFormation parameters in JSON format
stack-name	CloudFormation stack name
template-path	Path to CloudFormation template

Environment Variables

The action also sets the following environment variables:

Name	Description
DEPLOYMENT_PARAMETERS	CloudFormation parameters in JSON format
DEPLOYMENT_STACK_NAME	CloudFormation stack name
DEPLOYMENT_TEMPLATE_PATH	Path to CloudFormation template

Usage

Basic Usage

- name: Extract CloudFormation Parameters
  uses: subhamay-bhattacharyya-gha/cfn-read-deployment-params-action@main
  id: cfn-params

Custom Artifact Path

- name: Extract CloudFormation Parameters
  uses: subhamay-bhattacharyya-gha/cfn-read-deployment-params-action@main
  id: cfn-params
  with:
    artifact-path: './custom/path/to/deployment.json'

Using Outputs in Subsequent Steps

- name: Deploy CloudFormation Stack
  run: |
    aws cloudformation deploy \
      --template-file ${{ steps.cfn-params.outputs.template-path }} \
      --stack-name ${{ steps.cfn-params.outputs.stack-name }} \
      --parameter-overrides ${{ steps.cfn-params.outputs.parameters }}

Using Environment Variables in Subsequent Steps

- name: Deploy Using Environment Variables
  run: |
    aws cloudformation deploy \
      --template-file $DEPLOYMENT_TEMPLATE_PATH \
      --stack-name $DEPLOYMENT_STACK_NAME \
      --parameter-overrides $DEPLOYMENT_PARAMETERS

Input JSON Format

The action expects a JSON file with the following structure:

{
  "parameters": {
    "ParameterKey1": "ParameterValue1",
    "ParameterKey2": "ParameterValue2"
  },
  "stack-name": "my-cloudformation-stack",
  "template-path": "./templates/infrastructure.yaml"
}

Error Handling

The action will exit with an error code 1 in the following cases:

• The artifact file does not exist at the specified path
• The JSON file cannot be parsed correctly
• Required fields cannot be extracted from the JSON file

Requirements

• This action requires jq to be available on the runner (pre-installed on GitHub-hosted runners)

Examples

Complete Workflow Example

name: Deploy CloudFormation Stack

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

      - name: Extract CloudFormation Parameters
        uses: subhamay-bhattacharyya-gha/cfn-read-deployment-params-action@main
        id: cfn-params

      - name: Deploy CloudFormation Stack
        run: |
          aws cloudformation deploy \
            --template-file ${{ steps.cfn-params.outputs.template-path }} \
            --stack-name ${{ steps.cfn-params.outputs.stack-name }} \
            --parameter-overrides ${{ steps.cfn-params.outputs.parameters }} \
            --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM

Testing

This action includes test scripts to validate functionality:

• tests/test-valid-input.sh: Tests that the action works with valid JSON input
• tests/test-missing-file.sh: Tests error handling when file is missing
• tests/test-output-format.sh: Tests that output format matches expected structure

Run the tests with:

chmod +x tests/*.sh
./tests/test-valid-input.sh
./tests/test-missing-file.sh
./tests/test-output-format.sh

License

MIT