Skip to main content

​
Getting Started

Interact with Blocks on GitLab by mentioning @blocks in any issue or merge request comment with your request. Manage issues, answer questions, review MRs, implement changes, and more.
Connect GitLab via Settings > Integrations > GitLab in the Blocks dashboard. OAuth connects to a top-level GitLab group or your personal namespace. Subgroups are not supported — only top-level groups can be connected. Each team member must also link their individual GitLab account.
Delegate your request to a specific agent by mentioning the agent keyword in a slash command. Example: /claude, /codex, /gemini, /kimi. If none are mentioned, the request will default to your default agent. To change it: Dashboard → Agents → Set as default agent.

​
Bot Identity Setup

Blocks will respond on GitLab using the identity of whoever authorized the integration. To give Blocks a distinct identity — so responses appear from a dedicated bot account rather than a personal user — we recommend creating a separate GitLab user for this purpose before completing the integration. Steps:
  1. Create a new GitLab user account for your bot identity (e.g. Blocks Bot)
  2. Log into that GitLab account
  3. Create a new Blocks workspace user using that account’s email
  4. Invite the new Blocks user to your workspace
  5. While logged in as the bot’s Blocks account, go to Settings > Connected Accounts and connect the GitLab account
  6. Complete the GitLab integration via Settings > Integrations > GitLab while authenticated as the bot Blocks user
Once setup is complete, you can log back into your normal GitLab and Blocks accounts for everyday use. This is a one-time setup.

​
What Blocks Can Do

Blocks can help you with a variety of tasks on GitLab:
  • Answer Questions: Ask Blocks about an issue or MR
  • Update Issues: Request changes to an issue such as additional details with context from your codebase
  • Create New Issues: Ask Blocks to create additional tickets based on your requirements
  • Implementation: Ask Blocks to create an MR from an issue
  • MR Review: Ask Blocks to review a merge request. Optionally, include context for what to look out for
  • Make Changes: Ask Blocks to make changes to an open MR

​
Making a Request

Simply mention @blocks in any GitLab issue or MR comment followed by your request:
Session Context: Responding in a GitLab merge request thread will continue in the same session, preserving all context from the conversation. Creating a new comment on an issue or MR will create a fresh session with no prior context.

​
Plan Mode

Start a new session in Plan Mode to create an implementation plan before making changes:
Plan Mode allows you to collaborate on the approach before any code is written. Learn more about Plan Mode.
Plan Mode must be started with a new session and cannot be entered once implementation has begun.

​
Blocks Response Process

  1. Acknowledgment: Blocks will add 👀 (eye) emojis to indicate it has seen your message
  2. Dashboard Link: Blocks responds with a link to the dashboard where you can track progress
  3. Progress Updates: Blocks provides a realtime snippet about what it is currently working on
  4. Final Message: Blocks responds with a final message which summarizes what it did

​
Best Practices

  • Be Specific: Provide clear and detailed requests to get the best results
  • Use Context: Reference specific issues, sections of the code, or requirements when relevant
  • Check Progress: Use the dashboard link to monitor Blocks’ work on your request
  • Follow Up: You can continue the conversation by mentioning @blocks again with additional questions or clarifications

​
Next Steps

New to Blocks? Check out the Getting Started guide to learn the basics. Learn more about: