README.yaml

#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#

# Name of this project
name: github-action-terraform-plan-storage

# License of this project
license: "APACHE2"

# Copyrights
copyrights:
  - name: "Cloud Posse, LLC"
    url: "https://cloudposse.com"
    year: "2023"

# Canonical GitHub repo
github_repo: cloudposse/github-action-terraform-plan-storage

# Badges to display
badges:
  - name: Latest Release
    image: https://img.shields.io/github/release/cloudposse/github-action-terraform-plan-storage.svg?style=for-the-badge
    url: https://github.com/cloudposse/github-action-terraform-plan-storage/releases/latest
  - name: Last Updated
    image: https://img.shields.io/github/last-commit/cloudposse/github-action-terraform-plan-storage.svg?style=for-the-badge
    url: https://github.com/cloudposse/github-action-terraform-plan-storage/commits
  - name: Slack Community
    image: https://slack.cloudposse.com/for-the-badge.svg
    url: https://cloudposse.com/slack
description: |-
  A GitHub Action to securely store Terraform plan files in a cloud storage (S3 or Azure Blob Storage) with metadata storage in cloud document database (DynamoDB or CosmosDB).

# Introduction to the project
introduction: |-
  A Github Action to securely store Terraform plan files in a cloud storage (S3 or Azure Blob Storage)  with metadata
  storage in cloud document database (DynamoDB or CosmosDB). This is useful in CI/CD pipelines where you want to store
  the plan files when a feature branch is opened and applied when merged.

# How to use this module. Should be an easy example to copy and paste.
usage: |2-

  ## AWS (default)

  Standard usage for this action is with AWS. In AWS, we store Terraform plan files in a S3 Bucket and store metadata in DynamoDB. Specify the DynamoDB table name and S3 bucket name with `tableName` and `bucketName` respectively.

  The filepath in S3 and the attributes in DynamoDB will use the given `component` and `stack` values to update or create a unique target for each Terraform plan file.

  The plan file itself is pulled from or writen to a local file path. Set this with `planPath`.

  Finally, choose whether to store the plan file or retrieve an existing plan file. To create or update a plan file, set `action` to `storePlan`. To pull an existing plan file, set `action` to `getPlan`.

  ```yaml
   - name: Store Plan
      uses: cloudposse/github-action-terraform-plan-storage@v1
      id: store-plan
      with:
        action: storePlan
        planPath: my-plan.tfplan
        component: mycomponent
        stack: core-mycomponent-use1
        tableName: acme-terraform-plan-metadata
        bucketName: acme-terraform-plans

   - name: Get Plan
      uses: cloudposse/github-action-terraform-plan-storage@v1
      id: get-plan
      with:
        action: getPlan
        planPath: my-plan.tfplan
        component: mycomponent
        stack: core-mycomponent-use1
        tableName: acme-terraform-plan-metadata
        bucketName: acme-terraform-plans
  ```

  ## Azure

  This action also supports Azure. In Azure, we store Terraform plan files with Blob Storage and store metadata in Cosmos DB.

  To use the Azure implementation rather than the default AWS implementation, specify `planRepositoryType` as `azureblob` and `metadataRepositoryType` as `cosmos`. Then pass the Blob Account and Container names with `blobAccountName` and `blobContainerName` and the Cosmos Container name, Database name, and Endpoint with `cosmosContainerName`, `cosmosDatabaseName`, and `cosmosEndpoint`.

  Again set the `component`, `stack`, `planPath`, and `action` in the same manner as AWS above.

  ```yaml
   - name: Store Plan
      uses: cloudposse/github-action-terraform-plan-storage@v1
      id: store-plan
      with:
        action: storePlan
        planPath: my-plan.tfplan
        component: mycomponent
        stack: core-mycomponent-use1
        planRepositoryType: azureblob
        blobAccountName: tfplans
        blobContainerName: plans
        metadataRepositoryType: cosmos
        cosmosContainerName: terraform-plan-storage
        cosmosDatabaseName: terraform-plan-storage
        cosmosEndpoint: "https://my-cosmo-account.documents.azure.com:443/"

   - name: Get Plan
      uses: cloudposse/github-action-terraform-plan-storage@v1
      id: get-plan
      with:
        action: getPlan
        planPath: my-plan.tfplan
        component: mycomponent
        stack: core-mycomponent-use1
        planRepositoryType: azureblob
        blobAccountName: tfplans
        blobContainerName: plans
        metadataRepositoryType: cosmos
        cosmosContainerName: terraform-plan-storage
        cosmosDatabaseName: terraform-plan-storage
        cosmosEndpoint: "https://my-cosmo-account.documents.azure.com:443/"
  ```

  ## Google Cloud

  This action supports Google Cloud Platform (GCP). In GCP, we store Terraform plan files in Google Cloud Storage and metadata in Firestore.

  To use the GCP implementation, specify `planRepositoryType` as `gcs` and `metadataRepositoryType` as `firestore`, then provide the following GCP-specific settings: `googleProjectId` to specify the project for both GCS bucket and Firestore, `bucketName` for GCS storage, and `googleFirestoreDatabaseName`/`googleFirestoreCollectionName` for Firestore metadata.

  The `component`, `stack`, `planPath`, and `action` parameters work the same way as in AWS and Azure examples.

  ```yaml
   - name: Store Plan
      uses: cloudposse/github-action-terraform-plan-storage@v2
      id: store-plan
      with:
        action: storePlan
        planPath: my-plan.tfplan
        component: mycomponent
        stack: core-mycomponent-use1
        planRepositoryType: gcs
        metadataRepositoryType: firestore
        bucketName: my-terraform-plans
        gcpProjectId: my-gcp-project
        gcpFirestoreDatabaseName: terraform-plan-metadata
        gcpFirestoreCollectionName: terraform-plan-storage

   - name: Get Plan
      uses: cloudposse/github-action-terraform-plan-storage@v2
      id: get-plan
      with:
        action: getPlan
        planPath: my-plan.tfplan
        component: mycomponent
        stack: core-mycomponent-use1
        planRepositoryType: gcs
        metadataRepositoryType: firestore
        bucketName: my-terraform-plans
        gcpProjectId: my-gcp-project
        gcpFirestoreDatabaseName: terraform-plan-metadata
        gcpFirestoreCollectionName: terraform-plan-storage
  ```

# Other files to include in this README from the project folder
include: []

# List any related terraform modules that this module may be used with or that this module depends on.
related:
  - name: "github-action-atmos-terraform-plan"
    description: "This Github Action is used to run Terraform plan for a single, Atmos-supported component and save the given planfile to S3 and DynamoDB."
    url: "https://github.com/cloudposse/github-action-atmos-terraform-plan"
  - name: "github-action-atmos-terraform-apply"
    description: "This Github Action is used to run Terraform apply for a single, Atmos-supported component with a saved planfile in S3 and DynamoDB."
    url: "https://github.com/cloudposse/github-action-atmos-terraform-apply"

# List any resources helpful for someone to get started. For example, link to the hashicorp documentation or AWS documentation.
references:
  - name: "Cloud Posse Documentation"
    description: "Complete documentation for the Cloud Posse solution"
    url: "https://docs.cloudposse.com"
  - name: "Reference Architectures"
    description: "Launch effortlessly with our turnkey reference architectures, built either by your team or ours."
    url: "https://cloudposse.com/"

# Contributors to this project
contributors: [] # If included generates contribs