Troubleshooting Build Pipeline Failures

This guide outlines common issues, their root causes, and solutions specific to our Unity build pipeline, which uses Game-CI on GitHub Actions.

Unity Build Errors

When Unity encounters a problem during the build process, the Game-CI: Build Unity project step fails, and you’ll see the failure reflected in the logs. These errors often stem from issues in the Unity project itself, such as script compilation errors, asset import problems, or build configuration issues.

How to Identify the Errors

Unity build errors can be located in the logs generated by the Game-CI: Build Unity project step. Here's how to locate and analyze these errors:

Access the Build Logs:
- Navigate to the failed job in the GitHub Actions interface.
- Click on the Game-CI: Build Unity project step in the job log to expand it.
Search for "Error":
- Use the browser's search functionality (usually Ctrl+F or Cmd+F) to search for the word Error in the logs.
- Look for error messages from Unity, which often indicate the root cause of the failure.
- The most useful messages usually precede the "Build Output" marker in the logs:
```
###########################
# Build output #
###########################
```
Common Unity Build Error Patterns:
- Script Compilation Errors:
  Example: Assets/Scripts/MyScript.cs(10,20): error CS1002: ; expected
  These errors indicate issues in your code that must be fixed before the build can proceed.
- Missing or Corrupted Assets:
  Example: Failed to import package: Packages/com.unity.render-pipelines.universal/Runtime/Shaders/UniversalForwardLit.shader
  Ensure that all required assets are available and properly configured.
- Build Configuration Errors:
  Example: BuildFailedException: Player export failed. Reason: Invalid BuildTarget
  Check your build settings and ensure they match the expected platform.
Download Logs for Local Analysis: If the error is unclear, download the full log from the GitHub Actions interface and analyze it locally. Look for keywords like Exception, Failed, or Error.

Fixing Unity Build Errors

After identifying the issue, address it in the Unity project:

For Script Errors:
- Open Unity locally and resolve compilation issues.
For Asset Problems:
- Ensure all necessary assets are imported and not corrupted.
- Reimport the asset manually if required.
For Build Configuration Issues:
- Verify your Player Settings, platform-specific settings, and other configurations.

GitHub Container Registry 403 Error

Symptom:
The Docker: Login to GitHub Container Registry or Docker: Build and push image step fails with a 403 Forbidden error.

Cause:
Transient authentication issues between GitHub Actions and the GitHub Container Registry.

Solution: Restart the failed build pipeline, authentication retries often resolve the issue.

Unity License Server Concurrency Issues

Symptom:
The Game-CI: Build Unity project step fails with errors related to Unity license activation.

Cause:
Multiple builds running simultaneously can cause Unity’s license server to block one of the requests.

Solution: Restart the failed pipeline.

Disk Space Issues

Symptom:
The pipeline fails with errors indicating insufficient disk space, often during the Game-CI: Build Unity project step or Docker build steps.

Cause:
Limited disk space on the runner due to temporary files or cached data.

Solution:

The Free Disk Space (Ubuntu) step in your workflow already clears space. If the issue persists:
- Manually clean the runner by removing large or unnecessary files.
- Ensure tool-cache is enabled if more aggressive cleanup is needed.

Library Cache Issues

Symptom:
The Game-CI: Build Unity project step fails due to corrupted or incompatible files in the Library directory.

Cause:
The cache may contain outdated or invalid files after changes to assets, packages, or project settings.

Solution:

Clear the cache by removing the cached Library directory. Update the cache key in the workflow to force a rebuild:
```
- uses: actions/cache@v2
  with:
    path: Library
    key: ClearCache-${{ github.run_id }}
```

GitHub Pages Artifact Deployment Issues

Symptom:
The Github Pages: prepare artefact for deployment or Deploy to GitHub Pages step fails.

Cause:
Issues may arise if the build artifact path is incorrect or the actions/upload-pages-artifact step doesn’t execute properly.

Solution:

Verify the path in the actions/upload-pages-artifact step matches the correct build output directory (build/WebGL/WebGL).
Ensure the deploy job includes the correct permissions for GitHub Pages.

Docker Build and Push Issues

Symptom:
The Docker: Build and push image step fails with errors during the build or push process.

Cause:
Common reasons include:

Incorrect Dockerfile paths.
Build arguments (SOURCE_PATH) not resolving correctly.
Network or authentication errors with the container registry.

Solution:

Restart the build first to see if it is a temporary issue - otherwise proceed with the following steps
Confirm the context and file paths in the Docker build step.
Verify that build-args matches the correct path to your Unity WebGL build output (build/WebGL/WebGL).
Check Docker authentication using the docker/login-action.

General Best Practices

Monitor Logs:
Each step in your pipeline produces logs. Check these logs for detailed error messages and trace the failure to the specific step.
Retry Builds:
Issues such as transient authentication failures or license conflicts are often resolved by restarting the pipeline.
Version Control:
Pin versions of Game-CI tools and Unity to avoid unexpected failures due to updates:
```
unityVersion: 2022.3.8f1
customImage: unityci/editor:ubuntu-2022.3.8f1-webgl-2
```
Test Locally:
Run builds locally to catch issues before pushing changes to GitHub. Use Docker to test Game-CI locally:
```
docker run --rm -it -v "$(pwd):/project" unityci/editor:ubuntu-2022.3.8f1-webgl-2
```
Regular Maintenance:
Periodically update secrets, clean runners, and verify your project dependencies to maintain pipeline reliability.