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:

Init - Pluralith/actions/init
Run - Pluralith/actions/run
Comment - Pluralith/actions/comment

📍 The result looks like this:

⚙️ Getting Started

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

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)
Set PLURALITH_API_KEY as a repository secret. You can get your API Key through the Pluralith Dashboard.
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.
Set credentials for the providers of your choice as repository secrets (e.g. for AWS set AWS_ACCESS_KEY and AWS_SECRET_KEY).
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

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"

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:

Pluralith Init - Sets up and authenticates Pluralith
Pluralith Run - Runs pluralith graph to produce an infrastructure diagram as a PDF
Pluralith Comment - Posts the infrastructure diagram created in Pluralith Run as a GitHub comment to a pull request or commit

📦 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?

Sign up for the alpha over on our Website
Join our Subreddit
Check out our Roadmap and upvote features you'd like to see
Or just shoot us a message on Linkedin:
- Dan's Linkedin
- Phi's Linkedin

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

Pluralith / actions