Lab 5 - Integrating Confluence for Sprint Documentation and GitHub for Bug Management

In this tutorial, I’ll guide you through integrating Confluence for sprint documentation and GitHub for bug management within the context of the previous tutorials (unit, integration, E2E testing, and Jira/Xray/Zephyr for Scrum and test management). We’ll continue with the Spring Boot Book Management API and Express.js User Management API projects, using Jira to manage Scrum workflows, Xray/Zephyr for test management, and now adding Confluence for centralized sprint documentation and GitHub for bug tracking. This setup will enhance collaboration, traceability, and transparency across your team.

Overview

We’ll extend the Scrum workflow established in the previous tutorial by:

  1. Using Confluence to document sprint planning, retrospectives, and other sprint-related information, linking it with Jira for seamless collaboration.
  2. Integrating GitHub with Jira to manage bugs, allowing developers to track and resolve issues directly from their code repositories while maintaining visibility in Jira.

We’ll continue with the two projects:

  • Book Management Scrum (BMS): Spring Boot API for managing books.
  • User Management Scrum (UMS): Express.js API for managing users.

Prerequisites

  • Jira Projects: Ensure the Book Management Scrum (BMS) and User Management Scrum (UMS) projects are set up in Jira, as described in the previous tutorial, with sprints, epics, stories, sub-tasks, and test cases managed via Xray/Zephyr.
  • Confluence Account: Access to a Confluence instance (Cloud or Server/Data Center) linked to your Jira instance. You can sign up for a free trial on Atlassian’s website if needed.
  • GitHub Repositories:
    • Create a GitHub repository for the Spring Boot project (e.g., book-management-api).
    • Create a GitHub repository for the Express.js project (e.g., user-management-api).
  • Spring Boot and Express.js Projects: Use the projects from the previous tutorials, with APIs running at:
    • Spring Boot: http://localhost:8080/api/books
    • Express.js: http://localhost:3001/api/users

Part 1: Integrating Confluence for Sprint Documentation

Step 1: Set Up Confluence Spaces for Sprint Documentation

Confluence will serve as the centralized hub for sprint documentation, including sprint plans, meeting notes, and retrospectives, linked to Jira for traceability.

  1. Create Confluence Spaces:

    • Log in to Confluence.
    • Click Spaces > Create Space.
    • Create a space for the Book Management Scrum project:
      • Name: Book Management Documentation
      • Key: BMDOC
      • Description: “Documentation for the Book Management Scrum project, including sprint plans and retrospectives.”
    • Create a space for the User Management Scrum project:
      • Name: User Management Documentation
      • Key: UMDOC
      • Description: “Documentation for the User Management Scrum project, including sprint plans and retrospectives.”

  2. Link Confluence Spaces to Jira Projects:

    • In Jira, go to the Book Management Scrum (BMS) project.
    • Navigate to Project Settings > Application Links (or Integrations, depending on your Jira version).
    • Link the Book Management Documentation Confluence space to the BMS project by entering the space URL (e.g., https://your-confluence-instance.atlassian.net/wiki/spaces/BMDOC).
    • Repeat for the User Management Scrum (UMS) project, linking it to the User Management Documentation space.

  3. Create a Sprint Documentation Structure:

    • In the Book Management Documentation space, create a page hierarchy:
      • Parent Page: Sprint Documentation
      • Child Pages:
        • Sprint 1 - Book CRUD
        • Sprint 2 - Book Search (for future sprints)
    • On the Sprint 1 - Book CRUD page, add sections for:
      • Sprint Goal: “Implement basic CRUD operations for books.”
      • Sprint Plan: Link to Jira stories (e.g., Add a New Book, View All Books).
      • Meeting Notes: For sprint planning, daily stand-ups, and retrospectives.
      • Test Reports: To embed Xray/Zephyr test execution reports.
    • Repeat for the User Management Documentation space, creating a Sprint 1 - User CRUD page with similar sections.

Step 2: Document Sprint Planning in Confluence

  1. Use a Sprint Planning Template:

    • In Confluence, go to the Sprint 1 - Book CRUD page.
    • Use Confluence’s Sprint Planning template (or create a custom one):
      • Click Create > Search for “Sprint Planning” in the template library.
      • Add the sprint goal, team members, and a table for stories.
    • Embed Jira issues using the Jira macro:
      • Click Insert (+) > Jira Issue/Filter.
      • Search for issues in the BMS project with the filter project = BMS AND Sprint = "Sprint 1 - Book CRUD".
      • Display the issues as a table showing the issue key, summary, and status.

  2. Link the Confluence Page to the Jira Sprint:

    • In Jira, go to the Book Management Scrum project.
    • Navigate to Reports > Sprint Report for Sprint 1 - Book CRUD.
    • Click View Linked Pages > Create Page.
    • In the Confluence dialog, select the Book Management Documentation space and create a page titled Sprint 1 - Book CRUD Report.
    • Link this page to the sprint, ensuring the sprint report in Jira is connected to the Confluence documentation.

  3. Document Daily Stand-Ups:

    • On the Sprint 1 - Book CRUD page, add a section for Daily Stand-Up Notes.

    • Use a table to log daily updates:

      Date Team Member Yesterday’s Work Today’s Work Blockers
      2025-04-03 Fatma Implemented POST endpoint Validate input data None

    • Encourage team members to update this table in real-time during stand-ups.

  4. Document the Sprint Retrospective:

    • At the end of the sprint (e.g., April 17, 2025), create a Retrospective section on the Sprint 1 - Book CRUD page.
    • Use Confluence’s Retrospective template:
      • Click Create > Search for “Retrospective”.
      • Add sections for What Went Well, What Could Be Improved, and Action Items.
    • Link action items to new Jira tasks by highlighting text and using the Create Jira Issue feature in Confluence:
      • Highlight “Improve input validation error messages” > Click Create Jira Issue > Create a task in the BMS project.

Step 3: Embed Test Reports in Confluence

  1. Embed Xray Test Reports:

    • In the Sprint 1 - Book CRUD page, add a section for Test Reports.
    • Use the Jira Issue/Filter macro to embed the Sprint 1 Book CRUD Test Execution report:
      • Filter: project = BMS AND issuetype = "Test Execution" AND summary ~ "Sprint 1 Book CRUD".
      • Display the test execution status (e.g., Passed, Failed).
    • Alternatively, use Xray’s Overall Requirement Coverage gadget:
      • Insert the gadget macro and configure it to show coverage for the BMS project.

  2. Embed Zephyr Test Reports:

    • If using Zephyr, go to the Tests menu in Jira and generate a Test Execution Results report for the Sprint 1 Regression Cycle - Books.
    • Export the report as a PDF and attach it to the Sprint 1 - Book CRUD page in Confluence, or use Zephyr Scale Reporting for Confluence to embed live reports:
      • Install Zephyr Scale Reporting for Confluence (a free app).
      • Insert a Zephyr macro (e.g., Test Execution Results by Cycle) and configure it for the BMS project.

Part 2: Integrating GitHub for Bug Management

Step 1: Set Up GitHub Repositories

  1. Create GitHub Repositories:

    • For the Spring Boot project, create a repository named book-management-api and push the code from the previous tutorials.
    • For the Express.js project, create a repository named user-management-api and push the code.

  2. Add Initial Code:

    • Ensure the Spring Boot project (book-management-api) includes the BookController, BookService, BookRepository, and Book model from the previous tutorials.
    • Ensure the Express.js project (user-management-api) includes the app.js, server.js, and SQLite database setup.

Step 2: Integrate GitHub with Jira

  1. Install the GitHub for Jira App:

    • In Jira, go to Apps > Explore More Apps.
    • Search for GitHub for Jira and install it.
    • Follow the prompts to connect your GitHub account:
      • Authenticate with GitHub and authorize Jira to access your repositories.
      • Select the book-management-api and user-management-api repositories to link with the BMS and UMS projects, respectively.

  2. Configure the Integration:

    • In the Book Management Scrum (BMS) project, go to Project Settings > GitHub Integration.
    • Link the book-management-api repository to the project.
    • Repeat for the User Management Scrum (UMS) project, linking the user-management-api repository.

Step 3: Manage Bugs with GitHub

  1. Log a Bug in Jira:

    • During test execution in the Sprint 1 Book CRUD Test Execution (from the previous tutorial), a test fails (e.g., “POST /api/books returns 500 error”).
    • Create a bug in Jira:
      • Summary: “POST /api/books returns 500 error”
      • Issue Type: Bug
      • Link to the Add a New Book story and the failed test case.
      • Assign to a developer (e.g., Salah).

  2. Create a GitHub Issue from Jira:

    • Open the bug in Jira (e.g., BMS-123).
    • Since GitHub is integrated, you’ll see a GitHub section in the issue view.
    • Click Create GitHub Issue:
      • Select the book-management-api repository.
      • The issue will be created in GitHub with the same title and description, including a link back to the Jira issue (BMS-123).
    • The GitHub issue (e.g., book-management-api#1) will be automatically linked to the Jira issue.

  3. Fix the Bug in GitHub:

    • Developer Salah opens the GitHub issue (book-management-api#1).
    • Salah creates a branch to fix the bug: 
      git checkout -b fix-post-500-error
    • Salah fixes the issue in the Spring Boot project (e.g., by adding proper error handling in BookController): 
      @PostMapping
public ResponseEntity<Book> createBook(@RequestBody Book book) {
    if (book.getTitle() == null || book.getAuthor() == null) {
        return ResponseEntity.badRequest().build();
    }
    return ResponseEntity.ok(bookService.saveBook(book));
}
    • Salah commits the changes with a reference to the Jira issue: 
      git commit -m "Fix POST /api/books 500 error - BMS-123"
git push origin fix-post-500-error
    • Salah creates a pull request (PR) in GitHub, linking it to the issue (book-management-api#1).

  4. Sync Bug Status with Jira:

    • When the PR is merged, the GitHub for Jira app automatically updates the Jira issue (BMS-123):
      • The issue status transitions to In Progress when the branch is created.
      • The issue status transitions to Done when the PR is merged (if configured in your Jira workflow).
    • The Jira issue will show the commit and PR details in the Development panel.

  5. Re-Test the Bug:

    • Re-run the failed test case in Xray/Zephyr to verify the fix.
    • Mark the test as Passed in the Sprint 1 Book CRUD Test Execution.
    • Update the bug status in Jira to Closed if your workflow requires manual closure.

Step 4: Document Bug Fixes in Confluence

  1. Create a Post-Mortem Page:

    • In the Book Management Documentation space, create a page under Sprint 1 - Book CRUD called Bug Post-Mortem.
    • Use the Incident Post-Mortem template in Confluence:
      • Add sections for Summary, Root Cause, and Resolution.
    • Embed the Jira bug issue (BMS-123) using the Jira Issue/Filter macro.
    • Add a link to the GitHub PR and commit using the PR URL (e.g., https://github.com/your-username/book-management-api/pull/2).

  2. Share with Stakeholders:

    • Publish the page and share it with stakeholders via email or by linking it in the sprint retrospective section.

Hands-On Labs

Lab 1: Document a Sprint Retrospective for User Management

  • Task: In the User Management Documentation space, document the retrospective for Sprint 1 - User CRUD. Include a section for action items and create a Jira task directly from Confluence.
  • Steps:
    1. Create a Retrospective page under Sprint 1 - User CRUD.
    2. Use the Retrospective template and add:
      • What Went Well: “Successfully implemented user CRUD operations.”
      • What Could Be Improved: “Add validation for duplicate emails.”
      • Action Items: “Implement email uniqueness check in POST /api/users.”
    3. Highlight “Implement email uniqueness check” and create a Jira task in the UMS project.

Lab 2: Manage a Bug for User Management in GitHub

  • Task: Log a bug in the User Management Scrum project for a failed test (e.g., “POST /api/users allows duplicate emails”), create a GitHub issue, and fix it.
  • Steps:
    1. Create a bug in Jira (UMS-123): “POST /api/users allows duplicate emails.”
    2. Create a GitHub issue in the user-management-api repository from Jira.
    3. Fix the bug in Express.js by adding email uniqueness validation: 
      app.post("/api/users", (req, res) => {
  const { name, email } = req.body;
  const existingUser = db
    .prepare("SELECT * FROM users WHERE email = ?")
    .get(email);
  if (existingUser) {
    return res.status(400).json({ message: "Email already exists" });
  }
  const insert = db.prepare(
    "INSERT INTO users (name, email) VALUES (?, ?)"
  );
  const result = insert.run(name, email);
  const newUser = db
    .prepare("SELECT * FROM users WHERE id = ?")
    .get(result.lastInsertRowid);
  res.status(201).json(newUser);
});
    4. Commit the fix with a reference to UMS-123, create a PR, and merge it.
    5. Verify the bug fix by re-running the test in Xray/Zephyr.

Lab 3: Embed a Test Coverage Report in Confluence

  • Task: In the Book Management Documentation space, embed a test coverage report for Sprint 1 - Book CRUD using Xray or Zephyr.
  • Steps:
    1. Generate a test coverage report in Xray (e.g., Overall Requirement Coverage) or Zephyr (e.g., Test Execution Results by Cycle).
    2. On the Sprint 1 - Book CRUD page, use the appropriate macro to embed the report.
    3. Share the page with stakeholders to review testing progress.

Key Concepts and Best Practices

  1. Confluence for Documentation:
    • Use Confluence as a single source of truth for sprint documentation, linking it with Jira to provide context and traceability.
    • Leverage templates (e.g., Sprint Planning, Retrospective) to standardize documentation and save time.
    • Embed Jira issues and test reports to keep all relevant information in one place.
  2. GitHub for Bug Management:
    • Integrate GitHub with Jira to streamline bug tracking and resolution, ensuring developers can work in their preferred environment while maintaining visibility in Jira.
    • Use commit messages and PRs to automatically update Jira issue statuses, reducing manual overhead.
  3. Collaboration and Traceability:
    • Link Confluence pages to Jira sprints and issues to ensure team members can navigate between tools seamlessly.
    • Document bug fixes in Confluence to build a knowledge base for future reference.

Additional Notes

  • Scaling Documentation: As your projects grow, consider creating Confluence spaces for each team or release cycle to keep documentation organized.
  • Automation: Use Jira Automation to trigger Confluence page creation when a sprint starts, or to notify stakeholders when a bug is resolved in GitHub.
  • Security: Ensure proper permissions in Confluence and GitHub to restrict access to sensitive information (e.g., test reports, bug details).

This tutorial enhances your Scrum workflow by integrating Confluence for sprint documentation and GitHub for bug management, building on the testing foundation established in previous tutorials. By completing the labs, you’ll gain hands-on experience in creating a collaborative, traceable, and efficient development process.

By Wahid Hamdi