Get Started

The landing page for the GitLab for Miro documentation.

GitLab for Miro is our app that lets you sync content between Miro and GitLab. 🔄

It links your GitLab projects to your Miro boards, automatically creating App Cards for your project work items. Just connect your instances and sync your projects to start importing your GitLab work items into Miro.

Before you begin

GitLab for Miro installation prerequisites.

Before getting started using GitLab for Miro, there are a couple of prerequisites:

An active GitLab account.
An active Miro account, with a board you'd like to use.

That's all! Once you have these, you're good to go. 👍

Install

Installation instructions for GitLab for Miro.

To install GitLab for Miro:

From your desired Miro board, click the Tools, Media, and Integrations button in the left-hand menu.
Click the Marketplace search option, type GitLab for Miro in the bar, and select the app.

GitLab for Miro now appears in the left-hand menu. 🙌

Connect

The start of the section on connecting GitLab and Miro for use by the app.

There are two options for connecting GitLab and Miro. You can connect a GitLab Cloud account or a Self-managed instance. The instructions for each process are below.

Note:

Initial setup

You may connect additional GitLab instances after installing the app. The instructions below outline the steps to create your first connection.

GitLab Cloud

How to connect a GitLab Cloud account to the app.

To connect your first GitLab Cloud account:

Click Connect GitLab and select the GitLab Cloud (gitlab.com) option.
The Authorization window appears.
Click Authorize GitLab for Miro to connect your account.

You're returned to your Miro board, and your new connection is shown.

Self-managed GitLab instances

How to connect Self-managed GitLab instances to the app.

Note:

Recommended method for teams

Self-managed GitLab instances can be connected in two ways. The OAuth application method is recommended for teams, but must be completed by a user with a GitLab admin role.

Any GitLab account holder may complete the Personal Access Token method.

Connect via OAuth application

This method is recommended for enabling teams in Miro to access the app, but a GitLab admin must complete it. To connect via OAuth application:

Click Connect GitLab and select the Self-Managed GitLab option.
Click the OAuth Application option.
The Setup OAuth Application wizard appears.
Follow along with the setup steps, then enter your credentials in the provided fields.
1. Credentials needed: GitLab Instance URL (e.g., https://gitlab.example.com), Application ID (Client ID), and Secret (Client Secret).
Click Create Application.
The app shows an OAuth Application Saved confrmation screen with the prompt: Woul dyou like to connect now?
- 1. Click Yes, Connect to authorize your personal account immediately. A pop-up opens on your GitLab instance. Authorize it, and the pop-up closes with a Successfully Connected confirmation.
- 1. Click No, Later to finish setup without first connecting your personal account.

You're returned to your Miro board, and your new connection is shown.

Connect via Personal Access Token

How to connect the app to GitLab via Personal Access Token.

To connect via Personal Access Token:

Click Connect GitLab and select the Self-Managed GitLab option.
Click the Personal Access Token option.
The Connect with Personal Access Token wizard appears.
Follow along with the setup steps, then enter your credentials in the provided fields.
1. Credentials needed: GitLab Instance URL (e.g., https://gitlab.example.com) and Personal Access Token.
Click Connect.
The panel shows a success message with a green check.

You're returned to your Miro board, and the new connection is shown.

Note:

Personal access tokens expire.

Connections made via personal access token eventually expire. The app will warn you before your token expires. When it does expire:

Go to your GitLab instance and create a new Personal Access Token with the same scopes.
In the Miro panel, go to the connections view and click Add Connection.
Follow the setup wizard again with the new token credential.

Revoke a Personal Access Token

How to revoke a personal access token connection.

Removing a personal access token connection in the app disconnects it on the Miro side, but does not revoke the token in GitLab. To fully revoke access:

Go to your GitLab instance, click User Settings → Preferences → Personal access tokens.
Find the Miro GitLab Integration token in the list.
Click the three-dot menu and select Revoke.

Link a project

How to link a Gitlb project to the app.

Link a GitLab project to begin adding work items to your Miro board. 🔗 To link your first GitLab project:

From the GitLab for Miro panel, click Add work items to board.
Select Link Project from the listed options.
Optional: Select your desired connection if you've set up more than one.
Search for your desired project or click the carrot to scroll through your options in the Project field.
Set any filters desired and choose which fields to show on the Miro cards.
Click Link.

A success message appears, the linked project is shown in the panel, and work items appear as App Cards on your board.

Imported Work Items

Information about app cards created in Miro based on imported Work Items from GitLab.

After successfully linking, the GitLab for Miro app creates App Cards on the current board for every work item that matches your filters. Each card shows the work item title, GitLab status, assignee, and any labels you chose to appear.

The cards are added to your board at the cursor position. You may move and arrange them as you would any other Miro element.

Sync for the first time

How to sync your connection for the first time.

The Sync action pulls the latest data from GitLab and updates your cards. 🔄 It runs on demand. To sync your current work items:

In the main projects view, select your desired linked project card.
Click Sync on that project card to update just that project.
Alternatively: Click Sync All in the Linked Projects section header to update every linked project at once.