TeamCity : control branch under test via a configuration parameter

[SarahFrench]

Description

In TeamCity we sometimes need to manually trigger ad-hoc, custom builds.

These use cases for this feature:

• Running tests on a (patch) release branch, e.g. testing if a cherry-picked commit is ok on its new branch
• Testing branches generated from PRs in Magic Modules (e.g. https://github.com/modular-magician/terraform-provider-google/tree/auto-pr-8628)

Currently our new projects do not allow this to happen, and instead there is a singular default branch per project. The nightly tests default to main, the 5.0.0 test projects default to the feature branch` but this cannot be altered by users for one-off builds.

In the old TC projects, this feature was previously possible because there was a configuration parameter called BRANCH_NAME. The VCS root connection between TeamCity and GitHub was set to use this BRANCH_NAME value when setting the default branch, see %BRANCH_NAME% below:

Approaches

Abandoned approach : inheritance from parent projects, no Kotlin DSL code changes

The BRANCH_NAME parameter could be inherited by projects controlled by the Kotlin DSL code from a parent project that's manually managed. This would allow the 100% code configured projects to access a BRANCH_NAME value without updating the config code in .teamcity/.

However because the default branch isn't the same for all projects we would need to create new parent projects every time a project is made that shouldn't default to using main branch. This mixture of manual and code-controlled projects could get confusing quickly, and would require documentation for HashiCorp members to maintain the projects.

Chosen approach : update the Kotlin DSL to set a BRANCH_NAME parameter on the project it provisions

This PR uses the branch context parameter (a value people can edit within a Kotlin DSL-controlled project without issue) to set the BRANCH_NAME configuration parameter. The manually created VCS root will be set to use %BRANCH_NAME% as the default branch.

In the code, if the branch context parameter is unset it defaults to refs/heads/main. This means that users will only need to supply branch values when making a project that must default to a branch other than main.

Manual testing

This project in TeamCity cloud is set up to use the teamcity-sarah-test-20230811 branch in the downstream GA provider repo, which contains the changes this PR proposes.

Manual setup in my test TeamCity project

VCS root

Context parameter branch

Those two manually create things result in the parameter being set (and then inherited by all build configurations inside)
Note: the fact it says overridden (and matches the value above instead of being refs/heads/main) shows the code worked

Triggering a custom build that tests a different branch than the default branch

Normally, all builds in that project will use refs/heads/teamcity-sarah-test-20230811 for all builds, as it's the default branch.

I created a branch called teamcity-test-add-random-test that adds a new test TestAccSarah_please_work_pls (yep, really) to acctest package in the GA provider repository.

I then navigated to the acctest package's build configuration in my test project and triggered a new run of the build with customised parameters so that the build would use my branch above, and only look for the new test I added:

and the test was both successfully found and passed :)

Here is the link to that customised build.

Release Note Template for Downstream PRs (will be copied)

[modular-magician]

Hi there, I'm the Modular magician. I've detected the following information about your changes:

Diff report

Your PR generated some diffs in downstreams - here they are.

Terraform GA: Diff ( 3 files changed, 16 insertions(+), 2 deletions(-))
Terraform Beta: Diff ( 2 files changed, 11 insertions(+), 2 deletions(-))

[SarahFrench]

For anyone to also wanting to manually test this PR:

1. Go to the acctest package build configuration in my test project here : https://hashicorp.teamcity.com/buildConfiguration/TerraformProviders_Google_SarahTest202308112_GOOGLE_PACKAGE_ACCTEST
2. Click the ... next to Run. A pop-up should appear with a Parameters tab.
3. Click the Parameters tab and update:
   • BRANCH_NAME to refs/heads/teamcity-test-add-random-test
   • TEST_PREFIX to TestAccSarah
4. Click Run Build

[melinath]

Thanks for the thorough explanation of this PR! LGTM.

[SarahFrench]

I'll get this merged later today, as it requires a bunch of manual changes in TeamCity to accompany the code change. Thank you for the speedy review!

[SarahFrench]

This is now working in the generic nightly test projects but isn't available in the 5.0.0 testing projects yet