Skip to main content

Gitlab CI

Below you can find the official README of our dedicated Gitlab CI template.

View On Gitlab

Run Pluralith in Gitlab CI to automate your infrastructure documentation and save your team hours of busy-work. Pluralith posts a diagram of your infrastructure as a merge request comment. It also keeps a history of all changes made to your infrastructure which you can access at any time.

Pluralith diagrams also aggregate a variety of relevant data into the visual:

  • Change Highlighting
  • Drift Detection & Highlighting
  • Cost Data (via Infracost)
  • Compliance Data (coming soon)

The Result

See this merge request for a real life example

Getting Started

Follow these steps to get Pluralith running in your Gitlab CI workflow:

  1. Set PLURALITH_API_KEY and PLURALITH_PROJECT_ID as CI/CD variables. You can get your API Key and Project ID through the Pluralith Dashboard.
  2. Set credentials for the providers of your choice as CI/CD variables (e.g. for AWS set AWS_ACCESS_KEY and AWS_SECRET_KEY).
  3. Set a GITLAB_TOKEN as a CI/CD variable so Pluralith can post merge request comments. (Requires the api scope enabled to be able to read and write comments on merge requests)
  4. Create a new .gitlab-ci.yml file in your repo and copy the below example into it:
- if: $CI_PIPELINE_SOURCE == 'merge_request_event'

name: node:latest
entrypoint: [""]

.setup-terraform: &setup-terraform
- apt-get update && apt-get install -y gnupg software-properties-common curl
- curl -fsSL | apt-key add -
- apt-add-repository "deb [arch=amd64] $(lsb_release -cs) main"
- apt-get update && apt-get install terraform
- cd $TF_ROOT
- terraform init

.setup-pluralith: &setup-pluralith
- curl | sh

.init: &init
- pluralith init --api-key=$PLURALITH_API_KEY --org-id=$PLURALITH_ORG_ID --project-id=$PLURALITH_PROJECT_ID --project-name=$PLURALITH_PROJECT_NAME

.run: &run
- pluralith run --title=$TITLE --version=$VERSION --show-changes=$SHOW_CHANGES --show-drift=$SHOW_DRIFT --show-costs=$SHOW_COSTS --cost-mode=$COST_MODE --cost-period=$COST_PERIOD --export-pdf=$EXPORT_PDF

.comment: &comment
- compost autodetect update

- *setup-terraform
- *setup-pluralith
- *init
- *run
- *comment
# - - Terraform - -
TF_ROOT: terraform/application # Your Terraform project directory
TF_VERSON: 1.0.0 # Your preferred Terraform version (Note that Pluralith requires at least v0.15.3)
# - - Credentials - -
PLURALITH_PROJECT_ID: $PLURALITH_PROJECT_ID # ID of the project this run should be posted to
GITLAB_TOKEN: $GITLAB_TOKEN # For merge request comments the 'api' scope is required
# Set credentials for your cloud provider below (Example: AWS)
# - - Diagram - -
# Set your diagram details below, these will determine how the final diagram looks
TITLE: "Gitlab Demo" # Only relevant if EXPORT_PDF is true -> Custom title to be used for locally generated PDF
VERSION: "0.0.1" # Only relevant if EXPORT_PDF is true -> Add version string to locally generated PDF
SHOW_DRIFT: "false"
SHOW_COSTS: "false" # Only relevant if infracost is set up
COST_MODE: "delta" # Only relevant if infracost is set up
COST_PERIOD: "hour" # Only relevant if infracost is set up
EXPORT_PDF: "false"
  1. That's it! Create a merge request and see the magic happen in its comments!

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