Skip to content
ArchFoundry Docs Open the canvas

Import Terraform from a GitHub repository

Updated October 19, 2026Plans: Free, Pro, Enterprise

Overview

If your infrastructure is already written as Terraform, ArchFoundry can read it straight from a GitHub repository and draw it on the canvas. It reads one branch in memory, keeps no working copy, and writes nothing to the repository.

Prerequisites

  • An ArchFoundry account, on any plan: Free, Pro or Enterprise.
  • The owner or admin role in your ArchFoundry organization. Other members can import from a repository once it is connected, but only an owner or admin can connect it.
  • A GitHub repository with .tf files on at least one branch, and permission on GitHub to install apps on the account or organization that owns it.

Steps

  1. Open the canvas at app.archfoundry.ai/app.
  2. Press Ctrl+I (⌘I on a Mac), or choose Import from Terraform in the command palette.
  3. Look under or from a repository. If your repository is already listed there, click it and go to step 6.
  4. Click Connect GitHub. GitHub opens and asks which account to install ArchFoundry on.
  5. On GitHub, pick the account, then choose Only select repositories and pick the repositories ArchFoundry may read. Confirm, and GitHub sends you back to the import screen with the message Connected 1 repository from your account name.
  6. Pick the repository and the branch from the two lists at the top. ArchFoundry finds the directory that holds your root configuration.
  7. If your root configuration lives somewhere else, pick it under Or another configuration.
  8. Click Draw and the directory name, for example Draw infra/. When your configuration is at the top of the repository, the button reads Draw this repository.
  9. Review the summary, then click Put it on the canvas.

GitLab projects and access tokens are under GitLab, including self-hosted, or an access token, below Connect GitHub.

Example

This configuration is a small one to try the import with. Commit it as main.tf on a branch of the connected repository:

hcl
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"
}

resource "aws_subnet" "private_a" {
  vpc_id            = aws_vpc.main.id
  cidr_block        = "10.0.1.0/24"
  availability_zone = "us-east-1a"
}

resource "aws_s3_bucket" "assets" {
  bucket = "<your-project-name>-assets"
}

Change <your-project-name> to a name of your own. S3 bucket names are global, so the name has to be unused across all of AWS before you apply this. The import itself only reads it.

Expected result: the summary shows the VPC and its subnet under drawn as containers, and lists the files it read with the branch they came from. On the canvas the subnet sits inside the VPC, and the bucket is drawn as a card.

Verify it worked

  • The summary lists your .tf files, each with on and the branch name.
  • After Put it on the canvas, every resource in the summary appears as a card or a container.
  • Cards that AWS bills by the hour show a projected monthly price. Resources not yet in the price book appear under shown unpriced instead of with a guessed price.

Troubleshooting

The import says No repository is connected yet. Click Connect GitHub under it and follow step 5.

The import says No .tf or .tfstate files on your branch. The branch has no Terraform. Pick another branch from the list.

Some blocks are shown as code. A block that uses for_each, a module, or an expression ArchFoundry does not evaluate is shown as code rather than as a configurable card. Nothing is dropped, and nothing is priced from a guess.

Several files were merged into one document. Terraform reads a whole directory as one configuration, and the import does too. Because the result is not one file, pick the file to save back to when you commit from version control.

GitHub is waiting for an owner of that organization to approve ArchFoundry. A member asked an organization owner on GitHub to approve the install. Once they approve it, click Connect GitHub again.

Only an owner or admin can connect repositories. Ask an owner or admin of your ArchFoundry organization to do steps 2 to 5. After that, you can import from the repository yourself.

Those repositories are already connected to another ArchFoundry organization. Disconnect them in that organization first, under Git connections in Settings.

What the diagram does not show. The import draws what your code would create, not what exists in your account. Resources created outside Terraform are not on it. To draw what is actually running, connect an AWS account (read-only) from the import screen instead.

Next steps

  • Design your first architecture with Archie and ask Archie to change the imported diagram.
  • To add or remove repositories later, click Change repositories on the import screen, or in Settings under Git connections.