GitLab issues for Drupal.org projects

Drupal.org is in the process of migrating project issue queues from the internal Drupal.org issue system to GitLab issues on git.drupalcode.org. This page documents how GitLab issues work within the Drupal ecosystem, covering the full journey from creating an issue to collaborating on a fix, getting credit, and closing the issue. Where relevant, differences from the classic Drupal.org issue workflow are noted.

Your Drupal.org login works everywhere via single sign-on - no extra account is needed.

Overview: what changes and what stays the same

When a project's issues are migrated, they move from www.drupal.org/project/{name}/issues to git.drupalcode.org/project/{name}/-/work_items. Old URLs redirect automatically, and issue numbers (NIDs) are preserved as GitLab IIDs, so existing links in commit messages, blog posts, and external references continue to work. Note that from that point on, issue internal IDs are independent per project, so the IID (Internal Issue ID) is not unique within the GitLab instance the way NIDs were unique across Drupal.org.

What stays the same

• You can create issues without any special role.
• The contribution credit system is unchanged. Comments on GitLab issues sync to their contribution record automatically, and the credit UI still lives on Drupal.org.
• Shared issue forks remain the collaboration model. Drupal does not use personal forks.
• Familiar workflow conventions - Needs work, Needs review, RTBC, priority levels - carried over as scoped labels. Project maintainers can choose to continue using them or not.
• GitLab CI still runs tests the same way.
• Cross-references and parent/child relationships between issues still exist, with slightly different syntax (see Linking issues across systems below).

What is different

• Issues and merge requests now live alongside the code, pipelines, and CI logs on git.drupalcode.org.
• Only the original author or project maintainers can edit an issue description. On the old system, any logged-in user could edit an issue summary. If a description needs updating and you are not the author, leave a comment with the suggested wording.
• Labels and other metadata (priority, version, category, component, tags) require a Planner role or higher to edit directly in GitLab. Drupal.org provides a Labels management page so that any contributor can manage labels without a GitLab project role (see Labels management below).
• The issue cockpit block on project pages has been replaced by a simple "Issues" link that points to the correct queue (GitLab or Drupal.org depending on the project).
• Parent and related issues are now linked via full URL rather than entity reference fields. Both Drupal.org and GitLab issue URLs are supported.

Things that actually got better

• A modern issue editor with proper Markdown, real code blocks, syntax highlighting, image paste, and a mobile-friendly UI.
• Much better filtering, search, and saved queries on issue lists.
• Issue boards (Kanban-style) are available for projects that want them.
• Less context-switching during code review - issues, MRs, pipelines, and code are all in one place.

Creating an issue

Navigate to the project on git.drupalcode.org, click Work items in the left sidebar, then New item. The creation form asks only for a title and a description - labels and other metadata are added separately by users with the appropriate role. If a project has set up issue templates, you will see them in a dropdown when composing the description.

GitLab supports several work item types - Issues, Tasks, Incidents, and others. Always use the Issue type. All integrations between Drupal.org and GitLab are built against Issue items specifically. Maintainers may use other types for their own internal workflow, but those types are not connected to Drupal.org systems.

The first automated comment (DrupalBot)

Every new issue - and every migrated issue - receives an automated first comment from DrupalBot. This comment is the bridge to the Drupal.org tools that accompany each issue:

• A link to the contribution record on Drupal.org, where credit is tracked and managed.
• A link to the fork management page on Drupal.org, where you can create or request access to a shared issue fork.
• Once the contributor label UI ships, a link to the label management page on Drupal.org.

Note on migrated issues

On issues that were migrated from Drupal.org, DrupalBot appears as the author. This was a deliberate tradeoff: the GitLab API required choosing between preserving the original author name or preserving the original issue ID. The ID was preserved so that #123456 still maps to the same issue. The original author's name is recorded in the first line of the issue description.

Labels and issue metadata

All metadata for GitLab issues - category, priority, version, component, tags, and workflow state - is managed through labels. Labels are project-specific, giving maintainers full freedom to configure what makes sense for their project.

Who can set labels

Directly in GitLab, labels can only be added or changed by users with the Planner role or higher on the project. For all other contributors, the Drupal.org Labels management page provides an equivalent interface without requiring a GitLab project role. This page is linked from the DrupalBot automated comment on every issue. Maintainers can also grant the Reporter role to trusted community members to help with issue triage directly in GitLab.

Workflow state conventions

The familiar Drupal issue workflow conventions - Needs work, Needs review, RTBC - were preserved during migration as scoped labels. Each project's exact label set may vary, but the conventions carried over.

Convention	In GitLab
Needs work	state::needsWork label, or MR set to Draft
Needs review	state::needsReview label, or MR set to Ready
RTBC	state::rtbc label, or MR approval
Needs reroll	Push a rebase to the issue fork branch

Merge request states (Draft/Ready and approvals) are a useful parallel signal and often communicate the state of the actual code change more clearly than a label on the parent issue. Some projects lean on MR state, some on labels, some use both. Maintainers can also configure required approval rules per project to effectively enforce RTBC before merging.

Collaborating: forks and merge requests

Drupal's collaborative fork model is unchanged. There are no personal forks - contributors work together on a single shared issue fork per issue. GitLab does not support this model out of the box, so Drupal.org provides the fork management tooling.

Fork management on Drupal.org

Each GitLab issue has a corresponding Forks management page on Drupal.org, accessible via the DrupalBot comment or directly at new.drupal.org/drupalorg/issue-fork/management with a source_link parameter pointing to the GitLab issue URL. From this page you can:

• Create a new shared issue fork (a fork and a branch are created from the default branch).
• Request access to an existing fork.
• View existing merge requests for the issue.
• Open a new merge request.

Branching, committing, and merging happen in GitLab's native UI once you have fork access. Links to perform those actions in GitLab are provided from the fork management page.

Creating a fork and branch with a quick command

If you prefer to work directly from a GitLab issue comment, you can use the Drupal-specific custom quick commands:

• /do:fork - Creates a fork and a branch automatically from the default repository branch.
• /do:access - Grants the current user access to an existing fork.

Type the command as a comment on the GitLab issue and DrupalBot will carry out the action. Note that these commands are complementary to the fork management UI; for a more visual experience, use the Drupal.org fork management page.

Merge requests

Merge requests are created and managed natively in GitLab. Maintainers are encouraged to use the merge request listing - filtering by Draft/Ready state and approval status - as a primary view for reviewing what needs attention. Both states are filterable on the project's MR list.

Labels management

Each GitLab issue has a corresponding Labels management page on Drupal.org, accessible via the DrupalBot comment or directly at new.drupal.org/drupalorg/issue-labels/management with a source_link parameter pointing to the GitLab issue URL. This page lets any contributor manage labels on any issue without needing a GitLab project role - solving the most significant permission gap compared to the classic Drupal.org workflow.

The page is divided into two sections:

• Scoped labels - click any label pill to add it to the issue. Only one label per scope (e.g. one state::*, one priority::*, one category::*) is allowed at a time. Selecting a new label in the same scope automatically replaces the previous one.
• Plain labels - version labels, component labels, and other free-form tags. Start typing to filter the available labels for the project.

The left panel shows the labels currently applied to the issue and allows removing them individually. Once you have made your changes, click Save labels to apply them to the GitLab issue.

If the Labels management page is not yet available for a given issue, use the /do:label, /do:unlabel, and /do:relabel quick commands (see below) or ask a maintainer to apply the labels directly in GitLab.

Quick commands reference

Drupal.org provides a set of custom quick commands that can be typed as comments on any GitLab issue. They are prefixed with /do: to distinguish them from native GitLab quick actions. Use native GitLab commands where possible (for example, if you are a maintainer); these commands are intended for situations where you lack the project role to use the native GitLab equivalents. The commands listed below were available at the time of writing; for an updated list please visit the link above.

Command	Description
/do:fork	Creates a fork and a branch from the default repository branch.
/do:access	Gives the current user access to the existing fork.
/do:label ~list ~of ~labels	Adds labels to the issue (equivalent to GitLab's /label).
/do:unlabel ~list ~of ~labels	Removes labels from the issue (equivalent to GitLab's /unlabel).
/do:relabel ~list ~of ~labels	Replaces all labels on the issue (equivalent to GitLab's /relabel).
/do:assign @list @of @usernames	Adds assignees to the issue (equivalent to GitLab's /assign).
/do:unassign @list @of @usernames	Removes assignees from the issue (equivalent to GitLab's /unassign).
/do:reassign @list @of @usernames	Replaces all assignees on the issue (equivalent to GitLab's /reassign).

Linking issues across systems

During the transition period, some projects will have issues on Drupal.org and others on GitLab. The syntax for cross-referencing depends on the direction of the link.

From → To	Syntax
Drupal.org issue → Drupal.org issue	#123456: Drupal website oupedia.com with imported joomla template (unchanged)
GitLab issue → GitLab issue (same project)	#123456 (no brackets)
Cross-platform (either direction)	Full URL

For the Related issues field on Drupal.org issue forms, always use the full URL when pointing to a GitLab issue. When referring to a GitLab issue from another GitLab issue in a different project, also use the full URL.

See the GitLab documentation on crosslinking issues for more detail on GitLab-to-GitLab references.

Contribution records and credit

The contribution records system on Drupal.org is unchanged. Every comment you make on a GitLab issue syncs automatically to the issue's contribution record. The credit UI - where maintainers review and grant credit to contributors - still lives on Drupal.org.

Each GitLab issue has a corresponding contribution record page at new.drupal.org/contribution-record with a source_link parameter pointing to the GitLab issue URL. This page is linked from the DrupalBot automated comment on every issue.

The contribution record page also provides a Git commit message generator. Copy the generated message and paste it into the merge request commit or merge UI. Commit messages follow the Conventional Commits format as documented at drupal.org/node/3586390.

Issue boards and maintainer setup

Maintainers of migrated projects can configure issue boards to match their preferred workflow. A simple setup might have only Open and Closed columns. More structured projects can add columns based on scoped labels - for example, a column for state::rtbc - or define more complex transitions. This mirrors the flexibility offered to projects during the GitLab CI migration, where Drupal provides sensible defaults but each project can customise further.

Only maintainers can configure issue boards and set or change labels by default. Maintainers can grant the Reporter role to trusted contributors to help with triage and metadata management.

Closing an issue and getting credit

Issues are closed in GitLab by maintainers once the associated merge request is merged or the issue is otherwise resolved. When closing an issue:

1. Ensure the merge request (if any) is merged and CI is green.
2. Visit the issue's contribution record on Drupal.org (linked from the DrupalBot comment).
3. Review the list of contributors and grant credit where appropriate. Maintainers review and confirm credits; all commenting contributors are listed automatically.
4. Copy the generated commit message from the contribution record page and use it in the merge commit.

Contribution credit accrues on Drupal.org profiles as before. The workflow for credit is identical to that for classic Drupal.org issues.

Reporting bugs and giving feedback

Found a problem with the migration or the Drupal.org/GitLab integration? File it in the Drupal.org customisations issue queue.

To share feedback on the workflow, join the #gitlab-issues-feedback channel on the Drupal community Slack.

You can also subscribe to or comment on the following tracking issues:

• Opt-in your project for migration to GitLab Issues
• Provide feedback on the GitLab issue migration
• General issue for the GitLab migration

Notifications

GitLab sends email notifications for activity on issues and merge requests you are involved in. To receive them, make sure your Drupal.org/GitLab account has a real, deliverable email address - not a noreply@ address. You can verify and update this in your GitLab notification preferences: go to your avatar → Preferences → Notifications and check the Global notification email field.

You can set notification levels globally or per-project and per-group. The available levels are Watch (most activity), Participate (threads you are involved in), On mention, Disabled, and Custom. For active contribution, Participate is a sensible default.

Filtering notification emails

GitLab notification emails do not currently include the project name in the subject line, which makes inbox filtering less straightforward than with classic Drupal.org issue emails. However, GitLab adds a set of specific email headers to every notification that you can use to build precise filters in your email client.

The most useful headers for filtering are:

Header	What it contains	Filter use
X-GitLab-Project	The name of the project (e.g. drupalorg)	Filter all notifications for a specific project
X-GitLab-Project-Path	The full project path (e.g. project/drupalorg)	Distinguish projects with the same name in different groups
List-Id	The project path as an RFC 2919 mailing list identifier	Broad project-level filtering; widely supported by email clients
X-GitLab-(Resource)-ID	The ID of the issue or merge request	Filter notifications for one specific issue
X-GitLab-NotificationReason	Why you were notified: assigned, mentioned, subscribed, etc.	Separate direct assignments or mentions from general subscriptions

Most desktop email clients (Apple Mail, Thunderbird, Outlook) and web clients that support custom filters (Gmail, Fastmail) allow filtering on arbitrary headers. Refer to your email client's documentation for the exact steps. For the full list of available GitLab email headers, see the GitLab notification email headers documentation.

GitLab documentation reference

The official GitLab documentation is the canonical source for GitLab-native features.

Issues and work items

• Issues overview
• Create an issue
• Work items
• Description templates
• Crosslinking issues
• Issue boards

Labels and permissions

• Labels (including scoped labels)
• Roles and permissions

Merge requests

• Merge requests overview
• Draft merge requests
• Merge request reviews and approvals

Markdown

• GitLab Flavored Markdown

Notifications

• Notification emails
• Email headers you can use to filter email