The Adaptavist Group LogoDocumentation

How-To Guides

A section with various sets of instructions for common tasks in GitLab for Miro.

Here you'll find step-by-step guides for common GitLab for Miro use cases. Each guide on this page is independent.

All guides assume you are already connected to at least one GitLab instance. If you haven't been connected yet, you can begin with Get Started.

Available guides:

Instructions to link and configure projects in the app.

You will need: At least one active connection and access to the GitLab project you want to import.

To link and configure a project:

  1. In the GitLab for Miro panel, click + Add in the action bar.
  2. Select Link Project.
  3. Choose a connection from the dropdown.
  4. Type to search for a project, then select it from the results.
  5. On the filter screen, set any of the following (all optional):
    1. State- open, closed, or all
    2. Labels- one or more label values
    3. Milestone
    4. Assignee
    5. Search text
  6. Toggle the fields you want shown on each card.
  7. Click Confirm.

The app imports matching work items as App Cards on the current board.The project now appears in the panel's Linked Projects section.

To update filters later, click 🔧 Filters on the project card.
Note: If the team has reached its plan's project limit, a prompt appears to start a trial or upgrade. See

Plans and Licensing

.

How to add Work Items as a Group via the Search function.

You will need: At least one active connection. To use search to add specific work items as a group:
  1. In the GitLab for Miro panel, click + Add in the action bar.
  2. Select Search Work Items.
  3. Choose a connection.
  4. Optionally, narrow to a specific project or leave it set to search all projects.
  5. Apply any filters (labels, milestone, assignee, state, search text).
  6. Select the work items you want from the results list.
  7. Give the group a name. Optionally change the card color.
  8. Click Confirm to add the work items to the board.
The group appears in the panel's Linked Work Items Groups section. It has its own Sync button and can be deleted independently

Convert Sticky Notes to Work Items in bulk

Instructions for converting sticky notes to work items in bulk.

You will need: At least one active connection, a target GitLab project, and one or more sticky notes selected on the board.
  1. On the Miro board, select the sticky notes you want to convert.
  2. In the GitLab for Miro panel, click + Add in the action bar.
  3. Select Convert Sticky Notes. The view shows a count of your selected stickies (If the count is zero, go back to the board and select stickies first).
  4. Choose a connection and a target project.
  5. Optionally apply shared metadata to all converted work items: labels, milestones, and assignees.
  6. Name the work item group that will be created. A default name is pre-filled; change it if you like.
  7. Optionally change the card color.
  8. Click Confirm.
Each sticky note's text becomes a GitLab work item title, and the sticky is replaced by an App Card on the board.
Note: Only the sticky note's text is used as the work item title; body content is not mapped. There is no bulk way to add individual descriptions before converting. Edit work items one at a time after conversion if needed.

Create a GitLab Work Item from Miro

Instructions for creating a Work Item from Miro.

You will need: At least one active connection.
  1. In the GitLab for Miro panel action bar, click Create.
  2. Choose a connection.
  3. Search for and select a project.
  4. Fill in the work item fields. A Title is required (Optional fields: description, labels, assignee, milestone, due date, weight).
  5. Click Create.
After the work item is created, a success message appears with a link to the new work item in GitLab. If the project is already linked to this board, the new work item card appears automatically. If not, you can add it later via Search Work Items.

Edit Work Items and understand two-way sync

A section detailing how to edit work items and describing two-way sync.

Work Item Groups actions

Sync a Work Item Group

Click Sync on the work item group card in the Linked Work Item Groups section. This pulls the latest GitLab data for all work items in that group.

Add more Work Items to a group

Use Search Work Items to create a new group, or to check whether the group edit interface enables adding work items to an existing group.

Change the group's card color

Click the color swatch on the group card. Select a new color. All cards in the group update immediately.

Remove specific Work Items from a group

Check the group's manage/edit interface for a per-item removal option.

Delete a Work Item Group

Click Unlink on the group card and confirm. This removes the group and its App Cards from the board. The underlying GitLab work items are not deleted.
Note:Unlink removes the group from the board. The GitLab work items remain untouched.

Manage connections

Information and instructions on managing existing connections.

View your connections

From the main projects view, navigate to the Connections screen. This opens the connections view, which lists all of our connections.

Add another connection

Click New Connection at the bottom of the Connections screen. Follow the flow for a GitLab Cloud or Self-managed GitLab setup.

Disconnect a GitLab Cloud or OAuth connection

  1. Find the connection card with the OAUTH badge.

  2. Click Remove.

  3. Review the dialog, which lists any projects linked to this connection that will be removed from the app.

    App Cards already on the board stay on the board; GitLab data is unaffected.

  4. Confirm removal.

Disconnect a Personal Access Token connection

  1. Find the connection card with the Personal Access Token badge.

  2. Click Remove and confirm.

  3. After removal, a note appears instructing you to revoke the token in Gitlab.

    Follow the steps below.

Revoke a Personal Access Token in GitLab

  1. In GitLab, open your user menu and go to User Settings → Preferences.

  2. In the left sidebar, click Personal Access Tokens.

  3. Find the token named Miro GitLab Integration.

  4. Click the overflow menu and select Revoke.

Remove a team OAuth app (Admin only)

Only the user who created the OAuth app can see the Remove App button.

  1. Find the OAuth App card in the Connections screen.

  2. Click Remove App.

  3. Type delete in the confirmation field and confirm.

  4. Go to your GitLab Admin Area → Applications, find the Miro GitLab Integration app, and click Destroy to complete the removal on the GitLab side.

Change card colors

Instructions for changing the color of App Cards.

You will need: At least one linked project or work item group on the board.

Colors are set at the project or work item group level. One color applies to all cards in that project or group.

  1. In the GitLab for Miro panel, find the project card or work item group card you want to recolor.
  2. Click the color swatch in the top-right corner of the card. This opens the color picker.
  3. Select a new color.
All App Cards in that project or group update immediately. Color changes do not trigger a GitLab sync.

Recover or stop tracking deleted cards

Information on recovery or ending tracking on deleted app cards.

When you delete an App Card from the Miro board, a dialog appears with the following options:

  • No, recover: Recreates the card on the board with full visual fidelity and re-links it in the app. This is the safe, non-destructive option.

  • Yes, stop tracking: Removes the card from the app's tracking. The underlying GitLab work item remains unaffected; it will no longer appear on this board.

If you dismiss the dialog without choosing, the card is recovered automatically.

Accidentally stopped tracking?

Re-add the work item at any time:

  1. Click ➕ Add → Search Work Items.

  2. Search for the work item by title or ID.

  3. Select it and add it to a new or existing group.

Manage your subscription

Details on subscription management scenarios.

For a full explanation of plans, limits, and trial terms, see Plans and Licensing.

For questions about managing or upgrading a subscription, please contact us at miro-apps@adaptavist.com.

Open Account and Billing

In the GitLab for Miro panel's main projects view, click the plan badge in the footer row at the bottom of the panel. This opens the Account & Billing view.

View your current plan

The Account & Billing view shows your current plan, status, and how many projects you have used against your limit.

Start a 30-day trial of Business

You can start a trial from two places:

  • From the limit prompt — when you hit your plan's project limit, a dialog offers Start trial as an option.

  • From Account & Billing — click View plans, then select the trial option on the Business plan card.

No payment method is required. The trial lasts 30 days. Each plan can be trialled once per Miro team.

Upgrade to Business

  1. In Account & Billing, click View plans.

  2. On the Business plan card, choose Annual or Monthly billing.

  3. Click the Upgrade/Checkout button. You will be directed to a secure Stripe checkout.

  4. Complete payment. The panel automatically refreshes to your new plan.

Contact sales for Enterprise

The Enterprise plan card shows a Contact us button. Click it and follow the provided contact link or email.

Cancel a subscription

  1. In Account & Billing, click Manage.

  2. In the Salable customer portal that opens, follow the cancellation steps.

Alternatively, click Cancel directly in the Account & Billing view.

After cancellation, your subscription stays active until the end of the current billing period. The Account & Billing view shows "Cancels on [date]."

Resume a cancelled subscription

If your subscription is cancelled but still within the active period:

  1. In Account & Billing, click Resume.

  2. Confirm. Auto-renewal is re-enabled, and the cancellation is reversed.

Update payment details

  1. In Account & Billing, click Manage.

  2. In the Salable customer portal, update your payment method.

Note:If a payment fails, a banner appears in Account & Billing with an Update payment link.

Search documentation

Start typing to search the docs.