Best Practices for Displaying TeamCity Reports in Confluence
Effective display of TeamCity reports in Confluence helps teams monitor build health, share test results, and document release information without switching tools. Below are practical best practices, step-by-step setups, and tips to keep Confluence pages accurate, performant, and actionable.
1. Choose the right report types to surface
- Build status badges: Show overall build status (passing/failing) for quick at-a-glance health.
- Recent build summary: Display last successful/failed builds, duration, and responsible changes.
- Test reports: Surface aggregated pass/fail counts, flaky test indicators, and recent failures.
- Coverage and quality metrics: Include code coverage, lint, or static-analysis summaries.
- Artifacts and release notes: Link to build artifacts and auto-generated release notes.
2. Use the appropriate integration method
- Official macros/plugins: If available, install a TeamCity-Confluence plugin/macro to embed reports and badges directly. These typically handle authentication and live updates.
- Badges and images: Use TeamCity badge URLs or auto-generated images for simple status displays. Embed as images so they refresh when Confluence reloads pages.
- REST API + Confluence macros: For custom displays, fetch TeamCity data via its REST API and render with Confluence user macros or the HTML macro (if allowed).
- Automation (CI -> Confluence): Configure TeamCity build steps to update Confluence pages (via Confluence REST API) to publish final test summaries or release notes after successful builds.
3. Authentication and security
- Least privilege accounts: Use a service account with only necessary permissions for read or write actions.
- Secure storage of credentials: Prefer Confluence/TeamCity credential stores or secrets management. Avoid embedding credentials in page content or public macros.
- HTTPS and tokens: Use HTTPS endpoints and API tokens rather than passwords when possible.
4. Design for clarity and usability
- Keep pages scannable: Lead with overall status badge and short summary, then provide drill-down sections.
- Use tables for structured data: Present build lists, test summaries, and artifact links in tables for easy scanning.
- Color and icons: Use consistent color coding (green/yellow/red) and icons to indicate pass/warn/fail states.
- Version and date context: Always show build number, branch, and timestamp so readers know the report’s scope and freshness.
5. Automate updates and ownership
- Make updates automatic: Prefer live embeds, API-driven updates, or post-build Confluence updates to keep content fresh without manual edits.
- Assign ownership: Designate a team owner for CI pages to maintain relevance and respond to stale data or broken embeds.
- Update frequency controls: For expensive queries, cache results or update pages at controlled intervals (e.g., after each release or daily) rather than on every build.
6. Performance and scale considerations
- Limit heavy embeds: Avoid embedding large test logs or raw artifacts directly; link to those resources instead.
- Paginate long lists: Break long build histories into pages or show only recent N items with a link to the full history.
- Use summaries for large datasets: Show aggregated metrics (e.g., pass rate over 7 days) rather than raw test-by-test lists.
7. Troubleshooting common issues
- Broken badges/embeds: Verify plugin configuration, URL correctness, and service account permissions.
- Stale data: Check caching settings of the macro/plugin, and ensure API calls aren’t being rate-limited by TeamCity.
- Permission errors: Confirm the Confluence service account has access to TeamCity projects and artifacts, and that Confluence macros have necessary permissions.
8. Example implementations (quick templates)
- Build Summary header: badge + table (build #, status, duration, triggered by, link)
- Test Overview section: table (suite, total, passed, failed, flaky, last failure) + link to full report
- Release Notes section: autogenerated notes pulled from TeamCity artifacts or VCS changes
9. Checklist before publishing CI pages
- ✅ Service account configured with least privileges
- ✅ Reports auto-update or update-trigger configured
- ✅ Clear timestamps and build identifiers displayed
- ✅ Links to detailed logs/artifacts instead of embedding large files
- ✅ Page owner assigned and documented
10. Final tips
- Start small: surface the most actionable metrics first (status, recent failures), then expand.
- Iterate with users: collect feedback from developers and product owners to refine which reports matter.
- Monitor usage: remove or consolidate low-value pages to reduce maintenance.
Implement these practices to make Confluence a reliable CI dashboard that keeps teams informed while minimizing maintenance overhead.
Leave a Reply