Add default branch protection to tfcloud-mgmt repo

src/tfcloud-setup/tfcloud-resources.md

@@ -14,20 +14,20 @@ Next, copy and paste the following into `tfcloud_variables.tf`. The resources be
 {{#include tfcloud_variables.tf}}
 ```
 
-Next, copy and paste the following into `tfcloud_mgmt_project.tf` to create the Terraform Cloud project and workspace along with the associated GitHub repository. This also creates a workspace-scoped "variable set" resource to hold the credentials that Terraform Cloud will need in order to interact with both the Terraform Enterprise API and GitHub API. We follow Hashicorp's [recommended practice](https://developer.hashicorp.com/terraform/tutorials/cloud/cloud-multiple-variable-sets) of scoping the variable sets as narrowly as possible; we don't want any old project or workspace in our organization to be able to make changes to the Terraform Cloud organization.Again, you'll need to replace the placeholder values with ones that will work for you:
+Next, copy and paste the following into `tfcloud_mgmt_project.tf` to create the Terraform Cloud project and workspace along with the associated GitHub repository. This also creates a workspace-scoped "variable set" resource to hold the credentials that Terraform Cloud will need in order to interact with both the Terraform Enterprise API and GitHub API. We follow Hashicorp's [recommended practice](https://developer.hashicorp.com/terraform/tutorials/cloud/cloud-multiple-variable-sets) of scoping the variable sets as narrowly as possible; we don't want any old project or workspace in our organization to be able to make changes to the Terraform Cloud organization.
 
 ```hcl
 {{#include tfcloud_mgmt_project.tf}}
 ```
 
-Running `terraform apply` should show that 12 resources need to be created, so go ahead and confirm to get things set up!
+Running `terraform apply` should show that 14 resources need to be created, so go ahead and confirm to get things set up!
 
 ```sh
 $ terraform apply
 ...
-Plan: 12 to add, 0 to change, 0 to destroy.
+Plan: 14 to add, 0 to change, 0 to destroy.
 ...
-Apply complete! Resources: 12 added, 0 changed, 0 destroyed.
+Apply complete! Resources: 14 added, 0 changed, 0 destroyed.
 ```
 
 Congratulations! You now have a Terraform Cloud organization, project and workspace configured. You also have a GitHub repository that is linked up to that workspace.

src/tfcloud-setup/tfcloud_mgmt_project.tf

@@ -9,6 +9,24 @@ resource "github_repository" "tfcloud_mgmt" {
   }
 }
 
+resource "github_branch_default" "tfcloud_mgmt_main" {
+  repository = github_repository.tfcloud_mgmt.name
+  branch     = "main"
+}
+
+resource "github_branch_protection" "tfcloud_mgmt" {
+  repository_id  = github_repository.tfcloud_mgmt.name
+  pattern        = github_branch_default.tfcloud_mgmt_main.branch
+  enforce_admins = true
+
+  required_status_checks {
+    strict = false
+    contexts = [
+      "Terraform Cloud/${tfe_organization.example.name}/${tfe_workspace.tfcloud_mgmt_prod.name}",
+    ]
+  }
+}
+
 resource "tfe_project" "tfcloud_mgmt" {
   organization = tfe_organization.example.id
   name         = "tfcloud-mgmt"

src/tfcloud-setup/vcs-workflow-integration.md

@@ -22,13 +22,32 @@ That's clear evidence that it's treating the repo as that source of truth; the r
 cd ../
 git clone https://github.com/your-github-org-name/tfcloud-mgmt
 cd tfcloud-mgmt
-cp ../tfcloud-mgmt-scratch/*.tf
+cp ../tfcloud-mgmt-scratch/*.tf .
+git checkout -b tfcloud-mgmt
 git add .
 git commit -m "Add tfcloud-mgmt resources"
 git push
 ```
 
-Visiting the workspace in the Terraform Cloud UI, you should see a run be queued then the plan running. It should finish with no changes being detected. This now proves that the state, as managed by Terraform Cloud, is up to date with the code in the GitHub repository.
+````admonish note
+It's important to note that the above commit is made to a branch, rather than directly on the `main` branch. The repository was specifically configured to ensure that pushes can't be made directly to the `main` branch, but first have to be validated by a Terraform Cloud [speculative plan](https://developer.hashicorp.com/terraform/cloud-docs/run/remote-operations#speculative-plans).
+
+If you try to push directly to `main` you'll see an error similar to the following:
+
+```
+remote: error: GH006: Protected branch update failed for refs/heads/main.
+remote: error: Required status check "Terraform Cloud/your-tfcloud-org/tfcloud-mgmt-prod" is expected.
+To https://github.com/your-github-org/tfcloud-mgmt
+ ! [remote rejected] main -> main (protected branch hook declined)
+error: failed to push some refs to 'https://github.com/your-github-org/tfcloud-mgmt'
+```
+````
+
+In order to have Terraform Cloud start a speculative plan, open a PR from the newly created `tfcloud-mgmt` branch.
+
+The GitHub check should quite quickly progress from `Pending` to `All checks have passed` and the `Details` link will take you directly to the relevant run in the Terraform Cloud UI. Both the GitHub and Terraform Cloud UIs should show that no changes were detected.
+
+Merge the PR then confirm in the Terraform Cloud UI that another plan was run which similarly detected no changes.
 
 ## Tidy up