feat(samples): add Unity build pipeline with TeamCity integration

[gabebatista]

Issue number: N/A

Summary

Changes

This PR adds a new Unity build pipeline sample demonstrating how to deploy a production-ready Unity CI/CD infrastructure on AWS. The sample integrates Perforce (version control with code review), TeamCity
(CI/CD), Unity Accelerator (asset caching), and Unity Floating License Server with comprehensive documentation and a Docker image for Unity TeamCity build agents.

User experience

Before: Users had no reference sample showing how to deploy a complete Unity build pipeline on AWS. Individual Unity module documentation existed, but integration patterns were unclear.

After: Users can deploy a production-ready Unity build pipeline with terraform apply, following clear step-by-step documentation. The sample demonstrates best practices for integrating all components
with proper networking, security, and DNS configuration.

Testing This PR

To test this sample:

1. Review documentation: Read samples/unity-build-pipeline/README.md to understand the architecture and deployment steps
2. Build Docker image: Navigate to samples/unity-build-pipeline/docker/teamcity-unity-build-agent/ and run ./build-and-push.sh to verify the Unity TeamCity agent image builds successfully (~20
   minutes)
3. Validate Terraform: Run terraform init and terraform validate in the sample directory
4. Review configuration files: Check terraform.tfvars.example and variables.tf for proper variable definitions
5. Deploy and test infrastructure: Deploy all components and validate connectivity:
   • Configure terraform.tfvars with your Route53 domain, license server zip path, and TeamCity agent image URI
   • Run terraform apply to deploy all components
   • Verify all ECS services are healthy in the console
   • Get Perforce super user credentials:

     aws secretsmanager get-secret-value \
       --secret-id $(terraform output -raw perforce_super_user_username_secret_arn) \
       --query SecretString --output text
     aws secretsmanager get-secret-value \
       --secret-id $(terraform output -raw perforce_super_user_password_secret_arn) \
       --query SecretString --output text

   • Access P4 Swarm (Code Review) at https://swarm.yourdomain.com and verify login with Perforce credentials
   • Access TeamCity at the URL from terraform output -raw teamcity_url
   • Complete TeamCity initial setup wizard and create an administrator account
   • Verify build agents appear in Agents → Agents tab (may take 2-3 minutes):
     • Agents will initially appear in the Unauthorized tab
     • Click on the Unauthorized tab
     • Click Authorize next to each agent
     • Agents will move to the Connected tab once authorized
   • Create a test project to validate infrastructure:
     1. Click Create project
     2. Name it "Infrastructure Test"
     3. Click Create and then Skip VCS root creation (no repository needed for this test)
     4. Click Create build configuration
     5. Name it "Connectivity Test" and click Create
     6. Click Build Steps → Add build step
     7. Set Runner type to "Command Line"
     8. Set Step name to "Infrastructure Connectivity Test"
     9. Paste this script into Custom script:

#!/bin/bash
echo "=== Testing Infrastructure Connectivity ==="

# Test Perforce
echo "Testing Perforce..."
P4PORT=$(terraform output -raw p4_server_connection_string)
if p4 -p ${P4PORT} info; then
  echo "✓ Perforce connectivity successful"
else
  echo "✗ Perforce connectivity failed"
  exit 1
fi

# Test Unity Accelerator
echo "Testing Unity Accelerator..."
ACCELERATOR_URL=$(terraform output -raw unity_accelerator_url | sed 's|https://||')
if curl -f http://${ACCELERATOR_URL}:10080; then
  echo "✓ Unity Accelerator connectivity successful"
else
  echo "✗ Unity Accelerator connectivity failed"
  exit 1
fi

# Test Unity License Server (expected to fail without license)
echo "Testing Unity License Server..."
if [ -n "${UNITY_LICENSE_SERVER_URL}" ]; then
  curl -v ${UNITY_LICENSE_SERVER_URL} || echo "⚠ License server check failed (expected without valid license)"
else
  echo "⚠ License server not deployed"
fi

# Verify Unity installation
echo "Verifying Unity installation..."
ls -la /opt/unity/editors/*/Editor/Unity && echo "✓ Unity Editor found"

echo "=== Infrastructure tests complete ==="

10. Click Save
11. Click Parameters (left sidebar) → Add new parameter
12. Add environment variable UNITY_LICENSE_SERVER_URL with value from terraform output -raw unity_license_server_url (if deployed)
13. Click Run in the top right corner
14. Watch the build log - verify all connectivity checks pass (license server failure is expected without valid license)
15. If all tests pass, the infrastructure is working correctly
16. Clean up: Run terraform destroy to remove all resources

Checklist

If your change doesn't seem to apply, please leave them unchecked.

- I have performed a self-review of this change
- Changes have been tested
- Changes are documented

Breaking changes

No major breaking changes. This is a new sample. Minor additive changes to existing modules:
- Perforce module: Added shared_application_load_balancer_dns_name and shared_application_load_balancer_zone_id outputs for Route53 integration with P4 Swarm
- P4 Code Review module: Added checkov skip for ElastiCache (automatic backups not required for ephemeral cache data)

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created might not be successful.

[joshral7459]

Minor issues that prevent progress. Would be happy to do a working session and step through the deployment together.

[joshral7459]

My workspace root defaulted to my current directory which happened to be the unity sample folder in the toolkit. Did i miss a step to set it to something else?

[gabebatista]

The workspace location is not explicitly defined in that command. When you run:

p4 client -o -S //game/main | p4 client -i

Here's what happens:

Where the location comes from:

1. p4 client -o generates a client spec template with Perforce's default values
2. The Root: field in that spec determines the workspace location
3. By default, Perforce sets Root: to your current working directory (where you run the command)

The command breakdown:

• p4 client -o - Output a client spec template
• -S //game/main - Base it on the stream //game/main
• | p4 client -i - Pipe that spec to create the client

To control the workspace location:

You need to modify the client spec before piping it to p4 client -i. Here are better approaches:

Option 1: Set it explicitly

p4 client -o -S //game/main | \
  sed 's|^Root:.*|Root: /path/to/your/workspace|' | \
  p4 client -i

Option 2: Run from your desired directory

cd /path/to/your/workspace
p4 client -o -S //game/main | p4 client -i

Option 3: Edit manually

p4 client -S //game/main
# This opens an editor where you can set the Root field manually

The Root: field in the generated spec is what defines where files will be synced to on your local machine.

[joshral7459]

I was not able to access the swarm server at all.

[joshral7459]

also was not able to access. When i did nslookup in the beginning, there were no errors

[joshral7459]

Since the NLB is the public entry point, the record should point to the NLB alias rather than the ALB

[joshral7459]

is the intention to create a 2nd hosted zone for perforce and its subdomains as defined in the perforce module, route53 file?

[github-actions]

📚 Documentation Preview

✅ Preview deployed successfully!

🔗 Preview URL: https://aws-games.github.io/cloud-game-development-toolkit/preview-pr-775/

🔒 Maintainer Action Required

The preview requires approval before it's accessible. A maintainer must approve the GitHub Pages deployment in the Environments section.

Once approved, the preview will be accessible within 1-2 minutes.

Build Information

• Status: ✅ Deployed (awaiting approval)
• Commit: 8fa2549ad817298435b12065a4dcac679c41f1ad
• Workflow Run: #122

---

This preview will be automatically deleted when the PR is merged or closed.