❓ Troubleshooting & FAQ
This section covers common issues, troubleshooting steps, and frequently asked questions for Docker-BuildAgent and the Forge build orchestrator.
Troubleshooting
- Docker login/authentication errors:
- Ensure your
RegistryToken
is valid and has the correct permissions (write:packages
). - Use GitHub Actions secrets for sensitive values.
- Ensure your
- Image push fails:
- Check your network connection and GHCR access rights.
- .NET build issues:
- Ensure you have the .NET 8 SDK installed locally if running .NET builds outside the container.
- CI tool access issues:
- Ensure the CI environment has access to the required tools and permissions. The workflow sets up tools in the
/root/.dotnet/tools
directory and updates the PATH.
- Ensure the CI environment has access to the required tools and permissions. The workflow sets up tools in the
- Forge build type errors:
- Make sure you specify the correct
-type
argument (e.g.,docker
,node
).
- Make sure you specify the correct
FAQ
- Q: I get a permission denied error on build.sh or build.ps1
- A: Run
chmod +x build.sh
(Linux/macOS) or ensure PowerShell script permissions (Windows).
- A: Run
- Q: .NET build fails outside the container
- A: Make sure you have the .NET 8 SDK installed locally.
- Q: How do I pass secrets to Forge, Nuke, or Docker builds?
- A: Use environment variables or GitHub Actions secrets. Never hardcode secrets in scripts or Dockerfiles.
- Q: GitVersion or Nuke not found in CI?
- A: The workflow installs .NET tools globally, creates a symlink for GitVersion, and adds
/root/.dotnet/tools
to the PATH for reliable access.
- A: The workflow installs .NET tools globally, creates a symlink for GitVersion, and adds
- Q: How do I run a build for a specific project type?
- A: Use the
-type
argument with the build script, e.g.,./build.ps1 -type docker
or./build.ps1 -type node
.
- A: Use the
- Q: What happens when you run
ContainerCI
or thecontainer-ci
command?- A: The
ContainerCI
target runs the full build, versioning, tagging, and publishing pipeline in order:- Clean
- GetVersion
- ValidateInputs
- PrintInfo
- BuildContainer
- Tag
- Push
- Publish
- ContainerCI
- A: The
Each target depends on the previous one, ensuring the full pipeline is executed correctly.
For more help, see the project README or open an issue on GitHub.