How to start managing Github repository and branch protection by Terraform

Introduction

Usually, we create a Github repository on github.com manually and also update settings manually as it’s necessary. However, this manual configuration makes it hard for members, especially those who don’t have strong permission to see the settings of the repository, to know what is the repository settings, who is the admin, and who can push to protected branches.

In this post, to address the issue, I tried utilizing codify Github repository and settings. Terraform would be a potential solution, which has a provider for Github and with which we can make the information public so any member can see the repository settings in Terraform codes.

Preparation for managing Github with Terraform

1. Prepare backend.tf and provider.tf

2. Enable access to the backend.

1. Run terraform login if you use Terraform Cloud as a backend.
2. Read/Write permission if we use S3 as a backend.
3. No need for the local backend.

3. Run terraform init

terraform init

If you use Terraform Cloud, a new workspace will be created.

4. Generate Github token and set it to an environment variable

I used repo and delete_repo permission for my case, we can update according to the requirements.

Now the preparation is done.

Make resource with Terraform

1. Create Github Repository

2. Create Github Branch Protection

Other than those examples, we can manage many more GitHub settings with Terraform resources! For more details: https://registry.terraform.io/providers/integrations/github/latest/docs

Automate apply with Terraform Cloud

1. Configure Version Control in Terraform Cloud so, it can detect any change on the codes and check Auto apply to automate applying when a new commit is pushed to the default branch.
2. Test the configuration. Create a new PR in the repo configured in Version Control in Terraform Cloud, and confirme Terraform Cloud is executing terraform plan.
3. Merge the PR and confirm that the change is automatically applied by Terraform Cloud.

Import existing GitHub resources

When we start using Terraform for GitHub resource management, we might already have existing GitHub repositories and settings.

In this section, I’ll show how to import existing a GitHub repository. I’ll use one of my public repositories as an example for import.

The main steps to import an existing resource are as follows:

1. Prepare tf file for the target resource.
2. Execute terraform import for the target resource, which update Terraform state based on the tf file prepared above.
3. (Optional) fix tf file to make the tf file and the actual resource consistent.

1. Prepare tf file for the target resource

If you know more detail settings about the repository, you can write it as precisely as possible. I’m a little bit lazy to check one by one, so I’ll fix it after importing it.

2. Import the target resource

terraform import github_repository.<resource name> <repository name>

In my case, I ran the following command.

terraform import github_repository.eks eks

3. (optinal) Fix tf file

1. terraform plan can tell you if the imported resourece is same as code.
2. Fix the tf file until you get No changes. Your infrastructure matches the configuration as a result of terraform plan.

Final tf file for the example:

Finally, we can push the code to Git repository.

Notice: Even if you set GITHUB_TOKEN to a environment variable in Terraform Cloud, when you run terraform import, you would get the following error.

terraform import github_repository.eks eks
Acquiring state lock. This may take a few moments...
╷
│ Error: Cannot import non-existent remote object
│ 
│ While attempting to import an existing object to "github_repository.eks", the provider detected that no object exists with the given id. Only pre-existing
│ objects can be imported; check that the id is correct and that it is associated with the provider's configured region or endpoint, or use "terraform apply" to
│ create a new remote object for this resource.

If you get this error, you can resolve it by setting GITHUB_TOKEN in your local computer.

export GITHUB_TOKEN=xxxx

try again:

terraform import github_repository.eks eks
Acquiring state lock. This may take a few moments...
Import successful!
The resources that were imported are shown above. These resources are now in your Terraform state and will henceforth be managed by Terraform.

Github issue: https://github.com/integrations/terraform-provider-github/issues/647

Summary

In this post, I shared how to start managing GitHub repository and branch protection settings with Terraform. The codification of GitHub settings can help make the information public, which is very helpful for members who don’t have access to see those configuration.

ToDo

In some case, we might get the following error:

Error: This resource can only be used in the context of an organization, "xxxxx" is a user.

There’s already GitHub issues in the provider repo, but I haven’t confirmed how it’s fixed, so I’ll write another post about this issue after finding the solution.

• Some resources can only be used in the context of an organization
• Error: This resource can only be used in the context of an organization, "foo" is a user

References

• Github Repository
• Github Branch Protection
• terraform-import failure: Cannot import non-existent remote objec
• Some resources can only be used in the context of an organization
• Error: This resource can only be used in the context of an organization, “foo” is a user