Pluralith / actions

A collection of GitHub Actions to run Pluralith in CI and automate infrastructure documentation generation
Mozilla Public License 2.0
26 stars 3 forks source link
cicd github-actions pluralith terraform

GitHub Badge Blue

Pluralith GitHub Actions

This repo contains a collection of Github Actions to run Pluralith in CI and post infrastructure diagrams as pull request or commit comments. It currently contains three actions, we recommend running them in conjunction:

  1. Init - Pluralith/actions/init
  2. Run - Pluralith/actions/run
  3. Comment - Pluralith/actions/comment

 

πŸ“ The result looks like this:

Actions Comment

 

βš™οΈ Getting Started

Follow these steps to get Pluralith running in your GitHub Actions workflow:

  1. Create a new Pluralith workflow file in your repo at .github/workflows/pluralith.yml (View the full example at the bottom of this README to see how to structure a workflow YML file)

  2. Set PLURALITH_API_KEY as a repository secret. You can get your API Key through the Pluralith Dashboard.

  3. Ensure Pluralith is properly configured. There are multiple options to do this:

    • Commit a valid Pluralith Config File (pluralith.yml) to your repo
    • Set PLURALITH_ORG_ID, PLURALITH_PROJECT_ID and PLURALITH_PROJECT_NAME as environment variables in your workflow.
    • Pass org_id, project_id and project_name directly as parameters to the Pluralith Init step.
  4. Set credentials for the providers of your choice as repository secrets _(e.g. for AWS set AWS_ACCESS_KEY and AWS_SECRET_KEY)_.

  5. Set up Terraform and run terraform init. Hashicorp's hashicorp/setup-terraform action makes this a breeze. Check it out here or copy the example below into your steps:

# Set up Terraform
- name: Setup Terraform
  uses: hashicorp/setup-terraform@v1
  with:
    terraform_wrapper: false # This is recommended so the `terraform show` command outputs valid JSON

# Init Terraform project
- name: Terraform Init
  run: terraform init
  working-directory: path/to/terraform/root
  1. Set up and run Pluralith. Copy and paste the following three steps into your worflow:
# Set up and initialize Pluralith
- name: Pluralith Init
  uses: Pluralith/actions/init@v1.4.0
  with:
    terraform-path: "${{ env.working-directory }}/application"
    api-key: ${{ secrets.PLURALITH_API_KEY }}

# Run Pluralith to generate an infrastructure diagram and comment body
- name: Pluralith Run
  uses: Pluralith/actions/run@v1.4.0
  with:
    terraform-command: "plan"
    terraform-path: "${{ env.working-directory }}/application"
    show-changes: true
    show-drift: true
    show-costs: true # Requires Infracost to be set up in your pipeline

# Post the generated diagram as a GitHub comment
- name: Pluralith Comment
  uses: Pluralith/actions/comment@v1.4.0
  with:
    terraform-path: "${{ env.working-directory }}/application"
  1. That's it! Create a pull request and see the magic happen in its comments!  

πŸ›°οΈ Action Overview

Click the links below or navigate the repository above to learn more about the individual GitHub Actions for Pluralith:

 

πŸ“¦ Full AWS Example

If you are running AWS you can copy and paste the following into your .github/workflows/pluralith.yml. Adjust the paths to fit your Terraform project structure and you should be ready to go!

This example assumes a valid **pluralith.yml** config file in your Terraform project's root directory

on: [pull_request]
jobs:
  pluralith:
    runs-on: ubuntu-latest
    env:
      working-directory: terraform

    name: Run Pluralith
    steps:
      - name: Check out repository
        uses: actions/checkout@v2

      # Set up AWS credentials (using the aws-actions/configure-aws-credentials action)
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_KEY }}
          aws-region: eu-central-1

      # Set up Terraform
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v1
        with:
          terraform_wrapper: false # This is recommended so the `terraform show` command outputs valid JSON

      # Init Terraform project
      - name: Terraform Init
        run: terraform init
        working-directory: "${{ env.working-directory }}/application"

      # Set up and authenticate Pluralith
      - name: Pluralith Init
        uses: Pluralith/actions/init@v1.4.0
        with:
          terraform-path: "${{ env.working-directory }}/application"
          api-key: ${{ secrets.PLURALITH_API_KEY }}

      # Run Pluralith to generate an infrastructure diagram and comment body
      - name: Pluralith Run
        uses: Pluralith/actions/run@v1.4.0
        with:
          terraform-command: "plan"
          terraform-path: "${{ env.working-directory }}/application"
          show-changes: true
          show-drift: true
          show-costs: true # Requires Infracost to be set up in your pipeline

      # Post the generated diagram as a GitHub comment
      - name: Pluralith Comment
        uses: Pluralith/actions/comment@v1.4.0
        with:
          terraform-path: "${{ env.working-directory }}/application"

 

πŸ‘©β€πŸš€ Looking to become a tester or talk about the project?

Disclaimer: To properly use any of the Pluralith Actions you will need an API key. Sign up for the private alpha to get access!

Subreddit subscribers