Skip to main content

Github Actions

Below you can find the official README of our dedicated Pluralith Github Actions repo.

View On Github

We currently have three actions and 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.3.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.3.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.3.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:

  • 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.3.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.3.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.3.0
with:
terraform-path: "${{ env.working-directory }}/application"
caution

To get cost information in your diagrams Infracost needs to be set up in your pipeline.