GitLab Agile Portfolio Management- Hands-On Lab: Collaboration via MRs and Wikis

This Hands-On Guide walks you through creating a merge request and a Wiki in GitLab.

Estimated time to complete: 45 minutes

Objectives

A merge request is a proposal to incorporate changes from a source branch to a target branch. Merge requests help you manage the changes that are applied to your code. In this lab, you will learn how to set up and manage merge request approval rules in your projects. You can learn more about merge requests in the documentation.

Approval rules define how many approvals a merge request must receive before it can be merged, and which users should do the approving. They can be used in conjunction with Code owners to ensure that changes are reviewed both by the group maintaining the feature, and any groups responsible for specific areas of oversight. See the documentation to learn more.

Task A. Set merge request approval rules

  1. Navigate to your Family Budget Calculator project inside the Software > Core subgroup.

  2. In the left pane, click Settings > Merge Requests.

  3. Scroll down to the Merge request approvals section and click Add approval rule.

  4. In the Rule name field, enter Infra team.

  5. In the Groups field, select your Infrastructure group. You may need to use the ‘All groups’ option and search for your top-level group.

    To help reduce the search results, try searching for /awesome/infrastructure, or yourgroupname/awesome/infrastructure.

  6. Click Save changes.

  7. Back in the Merge request approvals section of the Merge Requests page, click Add approval rule to create a second project-level rule.

  8. In the Rule name field, enter Security operations.

  9. In the Groups field, select your Security group. You may need to use the ‘all groups’ option and search for your top-level group.

  10. Click Save changes.

  11. Back in the Merge request approvals section of the Merge Requests page, under Approval Settings, check the box next to Prevent editing approval rules in merge requests.

  12. In the same section, ensure that Prevent approval by the author is unchecked. This is necessary so we can approve our own merge requests in the training environment.

  13. Click Save changes.

Task B. Create a merge request

  1. In your Family Budget Calculator project, click Issues in the left pane.

  2. Click into your Identify tuning parameters to reduce performance bottlenecks issue.

  3. Click the down-arrow dropdown next to the Create merge request button on the issue landing page.

  4. Ensure Create merge request and branch is checked.

  5. In the Branch name field, change the text to read update-db-docs-perf-tools.

  6. Ensure that the Source is set to main.

  7. Click Create merge request.

  8. Type Draft: Add performance tools to Family Budget Calculator documentation in the Title field.

    Putting ‘Draft:’ at the beginning of your merge request means that the merge request will not occur until it has been marked as ready. This is used to note that a merge request is not ready to be merged yet, and to prevent accidental merges. Note that the Mark as draft checkbox below the title will also check automatically when ‘Draft:’ is added to the title.

  9. Remove Closes #<issue-number> from the Description field. We want to keep the original issue open for additional work.

    If a merge request has ‘Closes #’ in their description, the issue will be closed when the merge request is merged.

  10. Verify that you are assigned to the merge request by checking the Assignees section. Also note any labels inherited from the issue, and any approval rules inherited from project settings.

  11. Click the Create Merge Request button.

  12. From the merge request details page, select Code > Open in Web IDE to edit files on the update-db-docs-perf-tools branch.

    The Web IDE is an advanced editor with built-in ability to commit to your repository branches. You can use the Web IDE to make changes to multiple files directly from the GitLab UI. See the documentation to learn more.

  13. Click README.md from the left file pane.

  14. Paste the following into README.md, beginning on line 3.

    ## Performance tools
    The Family Budget Calculator currently uses HAProxy for load balancing.
    We are researching and testing additional tools to improve performance.
    
  15. Click Source Control in the left pane (the third button from the top).

  16. In the Commit message field, enter Update docs with performance tools

  17. Ensure that the message “Commit and push to update-db-docs-perf-tools branch” is written in the red ‘commit’ box underneath your commit message.

  18. Click Commit and push to update-db-docs-perf-tools branch.

Task C. Perform code review and merge changes

For advice on best practices when it comes to code reviews, see the documentation.

  1. Navigate to the Draft: Add performance tools to Family Budget Calculator documentation merge request by clicking on the red GitLab button in the bottom left corner of the Web IDE, and then clicking Go to Family Budget Calculator project on GitLab.

  2. Click on Code > Merge Requests, and then click on Draft: Add performance tools to Family Budget Calculator documentation.

  3. On the merge request page, click the Changes tab to see the changes that will be applied to the project’s main branch after merge.

    Code reviewers can critique individual lines of code and suggest changes. See the documentation to learn more.

  4. Click on the Overview tab.

  5. In the three dots menu to the right of the issue title, click Mark as ready to take the merge request out of draft mode. You will see that Draft: has been removed from the merge request’s title.

  6. Click Approve to approve the merge request. Note that the Merge button now appears since all requisite approvals have been applied.

  7. Scroll down to the comments field and type a comment in the comments field that reads: Approved. Ready to merge.. Click Comment to post the comment.

  8. Click Merge and observe the merge complete successfully.

  9. Navigate to the project landing page by clicking the Family Budget Calculator title tile in the top left corner. See that the README.md file on the main branch now includes your updates.

  10. In the left pane, click Code > Merge requests. The merge request will now appear under the Merged tab on this page.

Task D. Create a wiki for project documentation

If you don’t want to keep your documentation in your repository, but you want to keep it in the same project as your code, you can use the wiki GitLab provides in each GitLab project. Every wiki is a separate Git repository, so you can create wiki pages in the web interface, or locally using Git. GitLab wikis support Markdown, Rdoc, AsciiDoc, and Org for content. Wiki pages written in Markdown support all Markdown features, and also provide some wiki-specific behavior for links. You can read more about wikis here.

  1. Navigate to your Family Budget Calculator project in the Software > Core subgroup.

  2. In the left pane, click Plan > Wiki.

  3. Click Create your first page button in the middle of the page.

  4. In the Title section, type in Family Budget Calculator Documentation as the page title.

  5. Paste the following text in the content field underneath the title field.

    ## Summary
    
    The Family Budget Calculator helps households stay on budget and save for the future.
    
    ## Contact
    
    Contact <your-name> with questions or comments.
    
  6. Click Create Page. You should see a new Wiki page with the content you created.

If you’d like, edit the Family Budget Calculator Documentation page to add additional content or create additional wiki pages.

Lab Guide Complete

You have completed this lab exercise. You can view the other lab guides for this course.

Suggestions?

If you’d like to suggest changes to the GitLab Agile Portfolio Management Hands-on Guide, please submit them via merge request.

Last modified July 9, 2025: Project Management ILT Lab Rewrite (c12fa7aa)