Skip to content

Getting Started

This guide walks you through setting up Zenfra and running your first infrastructure workflow.

Prerequisites

Before you begin, make sure you have:

  • A Zenfra account with an organization
  • Access to a Git provider account (GitHub, GitLab, Bitbucket Data Center or Azure DevOps Server)
  • Access to at least one cloud account (AWS)
  • A repository containing Terraform or OpenTofu code

Step 1: Connect your source control

Zenfra needs access to your Git repositories to pull infrastructure code for each run.

This guide uses GitHub.com. For GitLab, GitHub Enterprise Server, Bitbucket Data Center and Azure DevOps Server, see Source Control; providers inside your network connect through a VCS Connector.

  1. Navigate to Integrations in the sidebar.
  2. Under Source Control Integrations, find GitHub and click Connect.
  3. Click Add Account and authorize the Zenfra GitHub App for the repositories it may access.
  4. Once connected, the integration shows as Connected.

Step 2: Connect your cloud account

Zenfra uses IAM role assumption to securely access your AWS account — no long-lived credentials are stored.

  1. Navigate to Integrations in the sidebar.

  2. Under Cloud Providers, click Amazon Web Services.

  3. Click New Integration and provide:

    • Name — a descriptive name for this integration (e.g., production-aws)
    • Role ARN — the ARN of the IAM role to assume
    • Region — the default AWS region
    • Leave Generate credentials in worker off for now; it is for private workers that should assume the role with their own AWS identity

  4. Copy the generated trust policy JSON and apply it to your IAM role in AWS.

  5. Click Verify to confirm Zenfra can assume the role.

For detailed setup instructions, see AWS Integration.

Step 3: Create your first stack

A stack connects your Git repository to a managed infrastructure lifecycle.

  1. Navigate to Stacks in the sidebar and click Create Stack.
  2. Complete the 4-step wizard:

Basic Info — enter a stack name, select a space, and choose a worker pool (the Public Worker Pool is fine to start with).

Git Config — select your integration, repository and branch, and the Path of your project inside the repository if it is not at the root. Choose the IaC engine (OpenTofu or Terraform) and its version. Leave Terraform State on Zenfra-managed; this choice cannot be changed after creation (see Terraform State).

Bundles — optionally attach configuration bundles, and attach the AWS integration from step 2 under Cloud Integrations with Read and Write permissions so runs receive credentials.

Review — confirm the configuration and create the stack.

Step 4: Trigger your first run

Once your stack is created, trigger a run to plan and apply your infrastructure.

  1. Open your stack and click the Trigger dropdown.
  2. Select Plan & Apply to create a tracked run that requires approval before applying.

  3. Watch the run progress through its phases:

    • Queued — waiting for a worker
    • Preparing — downloading source code and configuring the workspace
    • Initializing — running terraform init or tofu init
    • Planning — generating a plan of changes
    • Awaiting Approval — you review and confirm the plan
    • Applying — executing the approved changes
    • Finished — run completed successfully

  4. Review the plan output in the Planning phase.

  5. If the changes look correct, click Confirm, then Approve & Apply in the dialog that summarizes the resource changes. Discard cancels the run instead.

If the plan finds nothing to change, the run finishes right after planning with the outcome No changes; there is nothing to approve.

Step 5: Set up GitOps automation

Automate infrastructure runs by configuring push triggers on your stack.

  1. Open your stack and click Edit Stack from the actions menu.
  2. In the sidebar, select Source code.
  3. Under Automation Triggers, enable the Push Trigger toggle.
  4. Optionally add Project globs for paths outside your project root that should also trigger the stack (e.g., modules/**).
  5. Save your changes.

From now on a push to the tracked branch that changes a file under your project root, or one matching a project glob, triggers a run. If the stack has no project root, every push to the branch triggers it. Pull requests against the branch create plan-only runs regardless of the paths they touch.

What to explore next

  • Stacks — learn about stack configuration, settings, and run triggers
  • Runs — understand the run lifecycle and different run types
  • Spaces — organize stacks with hierarchical spaces
  • Worker Pools — set up private workers for your infrastructure
  • Configuration Bundles — share environment variables across stacks