GitHub and Hosted GitLab Integration

You can create or link to existing issues directly from Matrix Requirements. Once linked, issues are tracked for changes so that you can see when they have been resolved. All users will see the ID and the title of the issues right in the Matrix Requirements items and can jump to GitHub/GitLab from the Matrix items.

Backlinks to Matrix are added as notes to the issue, giving you direct access to the Matrix items related to the issue.

Configuration

Once the GitLab or GitHub  integration is installed and you have enabled it in the Extensions settings you have to configure it for each Matrix project you want to use it on. Before you do this you need an authentication token from GitHub or GitLab. To create this token follow these steps:

GitLab

• Generate a user account for Matrix in your GitLab instance. You can use any user account but it’s recommended to have a dedicated account only for Matrix access.
• Login as this user and make sure you can:
  • Create issues
  • Add notes
  • Delete issues
  • Remove notes
• Go to the user settings
• Click on “Access Tokens” on the left
• Create a new token with these permissions:
  • API
  • read_user
  • read_repository
  • write_repository
• Copy the token and keep it, you will need it later
• Go to the Extension Settings of the Matrix project you want to link and enable GitLab integration
• Enter the following information
  • The token (from above)
  • GitLab owner: This can be your username if this is a private repo or your organisation. It is the first section after gitlab.com: https://gitlab.com/<owner>/<repository>
  • GitLab repository: The repository to link to, you can always link to only one repository (but multiple Matrix projects can link to the same repository)
• Click on “add target projects and issue types”
  • “Project name” is the visible name of the project
  • “Project id” should be the same as the repository id above
  • “Task name” should be “Issue”
  • “Task id” should be “issue”
  • Leave the rest empty and press OK

GitHub

• Generate a user account for Matrix in GitHub. You can use any user account but it’s recommended to have a dedicated account only for Matrix access.
• Add the new user to you GitHub repository
• Login as this user and make sure you can:
  • Create issues
  • Add notes
  • Delete issues
  • Remove notes
• Go to the user settings
• Go to "Developer Settings"
• Open "Personal Access Tokens"
• Click on the "Generate new token" button
• Give the token a meaningful name and tick the "repo" checkbox
  

  

• Click on the "Generate new token" button
• In the next screen, copy the token and keep it, you will need it later
• Go to the Extension Settings of the Matrix project you want to link and enable GitLab integration
• Enter the following information
  • The token (from above)
  • GitHub owner: This can be your username if this is a private repo or your organisation. It is the first section after github.com: https://github.com/<owner>/<repository>
  • GitHub repository: The repository to link to, you can always link to only one repository (but multiple Matrix projects can link to the same repository)
• Click on “add target projects and issue types”
  • “Project name” is the visible name of the project
  • “Project id” should be the same as the repository id above
  • “Task name” should be “Issue”
  • “Task id” should be “issue”
  • Leave the rest empty and press OK

Once these steps are completed you should be good to go.

Using the integration

To test the setup, go to a Matrix item and press the Tools button at the top. In the menu select “Create and link GitLab task”. In the dialog enter some information, then submit. This will create a new issue in GitLab and add a link to the Matrix issue.

The integration offers the following functionality:

• Create and link to issues from Matrix
• Link to existing issues from Matrix
• Remove existing links
• Show GitLab issue status (open vs. closed) right in Matrix