Manage GitHub Users, Teams, and Repository Permissions | Terraform | HashiCorp Developer
HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream IT/SaaS Providers GitHub hosts code repositories so developers can build software for open-source and private projects in organizations. GitHub organization owners can control access to projects and data by managing their organization's settings, users, teams, and permissions. The Terraform GitHub provider allows you to programmatically manage your repositories, organization, teams, permissions, and projects.
Terraform provides several benefits over using the GitHub dashboard or CLI to manage your GitHub resources: Safety and consistency Defining your resources as code reduces the risk of human error. With Terraform, you can version control your configuration and ensure that the proper reviewers approve changes before merging them. Terraform allows you to track and update changes as your organization grows. Improved automation Terraform can create, update, and delete tracked resources without requiring you to manage dependencies.
With Terraform, you can develop modules for your organization, repositories, teams, and users that comply with your organization's policies. For example, you can use Terraform to ensure that your organization's security team has access to every new GitHub repository. In this tutorial, you will use Terraform and the GitHub provider to create resources and invite users to your GitHub organization as defined in CSV files.
In the process, you will learn how to use Terraform to simplify and automate your workflows. Prerequisites For this tutorial, you will need: the Terraform 1.0.5+ CLI installed locally. a GitHub account . a GitHub organization that you own. You can use an existing organization since you will destroy all the resources provisioned in this tutorial at the end. Otherwise, follow these instructions to create a new organization .
Configure your credentials The GitHub provider needs to authenticate to GitHub so it can manage its resources. In this tutorial, you will authenticate the provider using a personal access token. Follow the instructions in GitHub's documentation to create a personal access token for Terraform. To complete this tutorial, your personal access token must have at least the following permissions: The repo permisison for full control of private repositories.
The admin:org permission for full control of orgs and teams, read and write org projects The delete_repo permission to delete repositories Tip This token has access to your GitHub organization. Set an appropriate expiration date for your token, limit the token's scope to what is required, and save it in a safe place. Your personal access token will work with Terraform until it expires. Once you generate a personal access token, set it as an environment variable named GITHUB_TOKEN . $ export GITHUB_TOKEN = Then, create an environment variable named GITHUB_OWNER and set it to your GitHub organization.
If you do not specify a Github organization, Terraform will authenticate and manage resources on the access token user's individual user account. $ export GITHUB_OWNER = Terraform will use these environment variables to authenticate with GitHub and manage your organization's resources. Clone repository In your terminal, clone the example repository , which contains Terraform configuration to define a GitHub repository and team. $ git clone https://github.com/hashicorp-education/learn-terraform-github-user-teams Change into the repository directory. $ cd learn-terraform-github-user-teams Terraform configuration consists of blocks of code written in HashiCorp Configuration Language (HCL).
This configuration contains provider, local, data source, and resource blocks. You will learn more about each type of block as you review the configuration . Review users and team data Resource blocks are the primary way you interact with Terraform to manage a provider's objects. The example configuration references CSV files to set resource block arguments. This repository organizes the resource details across multiple CSV files. $ tree . ├── README.md ├── main.tf ├── members.csv ├── members.tf ├── repos-team │ ├── api.csv │ ├── application.csv │ └── infrastructure.csv ├── repositories.tf ├── team-members │ ├── developer-team.csv │ ├── devops-team.csv │ └── security-team.csv ├── teams.csv ├── teams.tf └── versions.tf There are two files at the top level of this directory: The members.csv file stores your organization members' data.
The teams.csv file stores your organization teams' data. The configuration is further divided into subdirectories to manage the teams and repository membership: The team-members directory contains CSV files that define team memberships. The CSV file name corresponds to the team name, and its contents contain the username and role of each team member. The repos-team directory contains CSV files that define repository and team permissions.
The CSV file name corresponds to the repository name, and its contents contain the team name and permission for the relationship. Using CSV files to populate Terraform resources and this specific file/directory structure is not required. However, this workflow enables you to simplify your Terraform configuration and better organize your resources. Open members.csv . members.csv username, role alex-tf-edu, member terraform-education1, member The first line in the CSV file is the header.
Each field in the header is a key for the corresponding value at the same position in the remaining rows. Each remaining row represents a user and must contain the same number of fields as the header. The header keys allow you to reference a specific user attribute in your Terraform configuration. Review the other CSV files if you would like. Initialize the configuration Initialize the Terraform configuration, which downloads and installs the github provider.
Later in this tutorial you will use terraform console , which requires initialization, to inspect the configuration in more detail. $ terraform init Initializing the backend... Initializing provider plugins... - Reusing previous version of integrations/github from the dependency lock file - Installing integrations/github v4.13.0... - Installed integrations/github v4.13.0 (signed by a HashiCorp partner, key ID 38027F80D7FD5FB2) Partner and community providers are signed by their developers.
If you'd like to know more about provider signing, you can read about it here: https://www.terraform.io/docs/cli/plugins/signing.html Terraform has been successfully initialized! You may now begin working with Terraform. Try running "terraform plan" to see any changes that are required for your infrastructure. All Terraform commands should now work. If you ever set or change modules or backend configuration for Terraform, rerun this command to reinitialize your working directory.
If you forget, other commands will detect it and remind you to do so if necessary. Review configuration Terraform parses all *.tf files in your directory and maintains a single state file that tracks the resources managed by the configuration in the directory. Defining resources in separate files makes your configuration easier to read and organize while still allowing you to define dependencies across files. Most of the Terraform configuration in this repository dynamically determines resource attributes from CSV files, so you will not need to modify most of the *.tf files for the workflow in this tutorial.
The only exception is the repositories.tf file, which gives you more control over repository-level settings like permissions and access. The example repository you cloned contains the following files: The versions.tf file defines Terraform settings, including the required providers Terraform will use to provision your resources. Providers are plugins that Terraform uses to interact with APIs. The main.tf f
The rest of this page is on the live site.