Github Actions
Below you can find the official README of our dedicated Pluralith Github Actions repo.
View On GithubWe currently have three actions and 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
andPLURALITH_PROJECT_NAME
as environment variables in your workflow. - Pass
org_id
,project_id
andproject_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
andAWS_SECRET_KEY
).Set up Terraform and run
terraform init
. Hashicorp'shashicorp/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"
caution
To get cost information in your diagrams Infracost needs to be set up in your pipeline.