# reiimer/terraform-github-actions architecture

> Architecture diagram of the GitHub repository reiimer/terraform-github-actions, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/reiimer/terraform-github-actions
- Repository: https://github.com/reiimer/terraform-github-actions

## Overview

Based on our analysis of the file tree and the README, this project is a GitHub Action designed to run Terraform commands (such as fmt, init, validate, plan, apply, and output) within a GitHub Actions workflow. Its purpose is to allow Terraform automation directly through GitHub workflows, handling inputs, outputs, and even posting comments on pull requests with the results.

##### Main Components
- GitHub Actions Workflow: This is the starting point where a repository’s workflow file (as shown in the README YAML snippet) triggers the action on events like pull requests.
- Terraform GitHub Action Container: The action itself is defined in the repository and encapsulates the logic, driven by a set of shell scripts from the src directory.
- Shell Script Components: Inside the src directory, you have several scripts – each handling a specific Terraform subcommand (e.g., terraform_fmt.sh, terraform_init.sh, terraform_validate.sh, terraform_plan.sh, terraform_apply.sh, and terraform_output.sh). There is also a main.sh that likely acts as the entry point to dispatch the correct subcommand based on inputs.
- Configuration & Inputs: Represent how inputs (defined in action.yml and described in the README) like tf_actions_subcommand, tf_actions_version, working directory, and others are received and processed.
- Output & Comments to GitHub: Reflect the branch that handles the comments on pull requests (via GITHUB_TOKEN) as well as output processing (tf_actions_output and tf_actions_plan_has_changes).
- External Dependencies: Include any external resources such as Terraform itself (installed at the determined version), the GitHub API for posting comments, and potentially Docker (as indicated by the Dockerfile) if the action is containerized.

##### Relationships and Interactions
- Inside this environment, branch out to each individual script (like terraform_fmt.sh or terraform_plan.sh) based on the input command.
- Subsequently, illustrate interactions such as:
- Passing environment variables (e.g., TF_LOG, TF_VAR_name) to the scripts.
- The execution of Terraform commands, and the collection of outputs, mapped back to the action's output fields.
- The conditional posting of results back to GitHub (e.g., comments on a pull request).
- Optionally, include a component for the Docker container if the Dockerfile is used for packaging the environment.

##### Architectural Patterns / Design Principles
- The project uses a modular, command-based approach where each Terraform subcommand is handled by its own script. This separation of concerns makes it easier to extend or debug.
- Inputs and environment variables are the primary configuration mechanisms, which enhance flexibility.
- The design emphasizes automation and continuous integration, aligning with GitHub Actions best practices.

##### Summary
- GitHub Workflow Trigger
- Docker Container (if applicable from Dockerfile)
- Action Metadata (action.yml and README configuration details)
- Main Entry Script (main.sh)
- Subcommand Scripts (terraform_fmt.sh, terraform_init.sh, terraform_validate.sh, terraform_plan.sh, terraform_apply.sh, terraform_output.sh)
- Inputs and Environment Variables (configuration parameters, secrets, etc.)
- Terraform Command Execution Layer
- GitHub API / Comments Posting Mechanism
- Examples (as a reference, show that there are use-case examples in the examples/ directory)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    WF["GitHub Workflow Trigger (Pull Request)"]:::trigger
    CONFIG["Action Metadata & Config (action.yml)"]:::config
    CONTAINER["Terraform GitHub Action Container"]:::container
    MAIN["Main Entry Script (main.sh)"]:::script

    %% External Dependencies
    TERRAFORM["Terraform CLI"]:::external
    GITHUB_API["GitHub API (Comments)"]:::external

    %% Subcommand Scripts Subgraph
    subgraph "Terraform Subcommand Scripts"
        FMT["Terraform Fmt (terraform_fmt.sh)"]:::script
        INIT["Terraform Init (terraform_init.sh)"]:::script
        VALIDATE["Terraform Validate (terraform_validate.sh)"]:::script
        PLAN["Terraform Plan (terraform_plan.sh)"]:::script
        APPLY["Terraform Apply (terraform_apply.sh)"]:::script
        OUTPUT["Terraform Output (terraform_output.sh)"]:::script
    end

    %% Flow Connections
    WF -->|"triggers"| CONFIG
    CONFIG -->|"loads into"| CONTAINER
    CONTAINER -->|"executes"| MAIN
    MAIN --> FMT
    MAIN --> INIT
    MAIN --> VALIDATE
    MAIN --> PLAN
    MAIN --> APPLY
    MAIN --> OUTPUT

    %% Subcommand interactions with external dependencies:
    FMT -->|"runs"| TERRAFORM
    INIT -->|"runs"| TERRAFORM
    VALIDATE -->|"runs"| TERRAFORM
    PLAN -->|"runs"| TERRAFORM
    APPLY -->|"runs"| TERRAFORM
    OUTPUT -->|"runs"| TERRAFORM

    PLAN -->|"posts comments"| GITHUB_API
    OUTPUT -->|"posts comments"| GITHUB_API

    %% Click Events
    click WF "https://github.com/reiimer/terraform-github-actions/blob/master/action.yml"
    click CONFIG "https://github.com/reiimer/terraform-github-actions/blob/master/action.yml"
    click CONTAINER "https://github.com/reiimer/terraform-github-actions/tree/master/Dockerfile"
    click MAIN "https://github.com/reiimer/terraform-github-actions/blob/master/src/main.sh"
    click FMT "https://github.com/reiimer/terraform-github-actions/blob/master/src/terraform_fmt.sh"
    click INIT "https://github.com/reiimer/terraform-github-actions/blob/master/src/terraform_init.sh"
    click VALIDATE "https://github.com/reiimer/terraform-github-actions/blob/master/src/terraform_validate.sh"
    click PLAN "https://github.com/reiimer/terraform-github-actions/blob/master/src/terraform_plan.sh"
    click APPLY "https://github.com/reiimer/terraform-github-actions/blob/master/src/terraform_apply.sh"
    click OUTPUT "https://github.com/reiimer/terraform-github-actions/blob/master/src/terraform_output.sh"

    %% Styles
    classDef trigger fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef config fill:#cceeff,stroke:#0066cc,stroke-width:2px;
    classDef container fill:#ccffcc,stroke:#009933,stroke-width:2px;
    classDef script fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#666666,stroke-width:2px;
```
