Quickstart Guide

Get up and running with Terrateam in minutes. Choose your starting point:

Try the demo repository Learn Terrateam's workflow with simulated infrastructure. No cloud credentials needed. Perfect for getting started.

Set up your own repository Jump straight into using Terrateam with your existing Terraform code and real infrastructure.

Prerequisites

• A GitHub account
• Administrator access to install the Terrateam GitHub app

Option 1: Try the demo (recommended)

Perfect for learning Terrateam. This demo uses null resources instead of real infrastructure, so you can learn Terrateam’s workflow without any cloud setup.

Terrateam Demo Repository

1. Fork the demo repository

   Click the link above and fork the repository to your GitHub account.

2. Enable GitHub Actions Workflows

   Forked repositories disable workflows by default for security reasons.

   • Go to your forked repository and click the Actions tab
   • You’ll likely see “Workflows aren’t being run on this forked repository”
   • Click on I understand my workflows, go ahead and enable them

3. Install the Terrateam GitHub App

   Sign up for Terrateam and install the GitHub app on your account/organization.

   Install Terrateam GitHub App

4. Try it out

   • Edit dev/main.tf - change count = 0 to count = 1
   • Create a new branch and push your changes
   • Open a pull request
   • Watch Terrateam automatically comment with the Terraform plan!

5. Apply the changes

   Comment terrateam apply on the PR to apply the changes.

What you’ll see

When you open your first PR, Terrateam will automatically comment with the terraform plan output:

This demo uses null_resource, which doesn’t provision anything. This is just a way to show how Terrateam runs the Terraform workflow safely.

Note

This demo doesn’t persist Terraform state between runs. Each terraform plan starts fresh, so you won’t see destroy operations for previously created resources. This keeps the demo simple, but real Terrateam deployments use persistent state backends.

Option 2: Set up your own repository

Ready to use Terrateam with your existing Terraform code? Here’s how to get started:

1. Install the Terrateam GitHub App

   If you haven’t already, install Terrateam on your GitHub account/organization.

   Install Terrateam GitHub App

2. Add the GitHub Actions Workflow

   Critical: The workflow file must be in your default branch (main or master)

   # Quick setup - copy/paste this entire block
   git checkout -b add-terrateam-workflow && \
   mkdir -p .github/workflows && \
   curl -o .github/workflows/terrateam.yml https://raw.githubusercontent.com/terrateamio/terrateam-example/refs/heads/main/github/actions/workflows/default/terrateam.yml && \
   git add .github/workflows/terrateam.yml && \
   git commit -m "Add Terrateam workflow" && \
   git push -u origin add-terrateam-workflow

   Alternative: Manually create .github/workflows/terrateam.yml and copy the contents from this workflow file.

   Next: Create a pull request and merge it into your default branch to activate the workflow.

3. Configure your repository

   Terrateam works automatically with most Terraform repositories. Simply ensure your repository has:

   • .tf files in your project
   • A valid Terraform configuration
   • Proper cloud provider credentials (configured as GitHub secrets or environment variables)

4. Create your first pull request

   • Make changes to any .tf file
   • Create a pull request
   • Terrateam will automatically run terraform plan and comment on your PR

5. Apply Changes

   Comment terrateam apply on your PR to execute the planned changes.

Troubleshooting

Terrateam isn’t commenting on my PR?

• Check your repository’s Actions tab for disabled workflows
• Verify the Terrateam GitHub App is installed on your repository
• Make sure your PR changes Terraform files (.tf files)

Next Steps

Learn how Terrateam works

Explore key Terrateam concepts

Set up cloud provider integration

Explore advanced workflows