| name | drupalorg-work-on-issue |
| description | Agentic workflow for contributing to a Drupal.org issue via GitLab MR. Orchestrates fork verification, directory alignment, remote setup, branch checkout, and the fix/push/pipeline loop.
|
/drupalorg-work-on-issue
Purpose: Agentic workflow for contributing to a Drupal.org issue via GitLab MR.
Usage: /drupalorg-work-on-issue <nid-or-ref>
The argument can be:
- A Drupal.org issue NID:
3586157
- A shorthand work item ref:
ai_context#3586157
- A full GitLab work item URL:
https://git.drupalcode.org/project/ai_context/-/work_items/3586157
All three formats are accepted by issue:show, issue:get-fork, and mr:list.
Instructions
When the user invokes /drupalorg-work-on-issue <nid>, execute the following workflow. Pause at
each checkpoint marked [PAUSE] — present findings and wait for the user to confirm
before proceeding.
Step 1: Fetch issue and fork details
Run both commands to gather context (substitute <nid> with whatever ref was provided):
drupalorg issue:show <nid> --format=llm
drupalorg issue:get-fork <nid> --format=llm
Report to the user:
- Issue title, status, project machine name
- Whether a fork exists and which branches are available
Directory detection: Before prompting the user, read CLAUDE.md in the current directory.
If it documents the path to the <project> module or repository, cd there automatically
and skip the directory prompt. Only fall back to running git remote get-url origin and
asking the user if CLAUDE.md provides no guidance.
Branch selection: Count branches from the issue:get-fork output that match <nid>-*:
- Exactly one match → select it automatically; no prompt needed.
- Multiple matches → list them and ask the user which to check out.
- No matches → note that no branches exist yet and ask the user how to proceed
(e.g. create a new branch from the upstream project default branch).
No fork at all (GitLab work item projects): If issue:get-fork reports no fork
exists AND the project uses GitLab work items (the ref is a project_name#nid or
work item URL, not a classic Drupal.org NID), offer to create one:
drupalorg issue:fork <ref>
The Drupal.org bot processes the comment asynchronously. Wait a few seconds, then
re-run drupalorg issue:get-fork <ref> --format=llm --no-cache to confirm the fork
exists before proceeding. To pick up an existing fork you don't yet have push access
to (Example #2 in the upstream docs), run drupalorg issue:get-access <ref> before
issue:setup-remote.
[PAUSE] Only pause here if the working directory could not be determined automatically
OR if multiple branches exist. Present your findings and wait for confirmation before
proceeding.
Step 2: Set up remote and check out the branch
Important: All git and drupalorg commands from this point forward must be run from
the project module directory (not the Drupal site root). Ensure you have cd'd into the
correct directory before executing any command below.
Once the directory and branch are confirmed:
drupalorg issue:setup-remote <nid>
drupalorg issue:checkout <nid> <branch>
Optional (GitLab work items): Self-assign so others can see you are working on
this issue:
drupalorg issue:assign <ref>
SSH remote URL check: issue:setup-remote sets the remote URL to HTTPS
(https://git.drupal.org/issue/<project>-<nid>.git). Contributors using SSH authentication
must switch to the SSH equivalent before pushing. After the remote is set:
git remote get-url drupalorg
Report the branch that is now active.
Step 3: Inspect the current MR state
Important: Run all commands from the project module directory.
Diff the branch first to understand what has already been changed vs. what is still
missing. Determine the upstream default branch from the fork data (e.g. main, 10.3.x),
then run:
git diff origin/<default-branch>...HEAD
Read this diff carefully before analysing the MR — it is the authoritative record of what
the branch already contains. Do not assume a file is unchanged without checking the diff.
drupalorg mr:list <nid> --format=llm
If mr:list returns no MRs:
- Report "No MR exists yet for this issue."
- Skip the MR inspection commands below.
- Proceed directly to the work loop (Step 4).
- After the first
git push, capture the GitLab MR-creation URL printed in the push
output and surface it to the user. Then re-run drupalorg mr:list <nid> --format=llm
to pick up the newly created MR IID before polling pipeline status.
If one or more MRs exist, for the relevant MR (confirm with user if multiple exist):
drupalorg mr:files <nid> <mr-iid>
drupalorg mr:diff <nid> <mr-iid>
drupalorg mr:status <nid> <mr-iid> --format=llm
Summarise:
- What the MR changes (files and diff summary)
- Current pipeline status (passing / failing / pending)
- If the pipeline is failing, fetch logs:
drupalorg mr:logs <nid> <mr-iid>
[PAUSE] Present your analysis of the MR and the pipeline results, then ask:
"What would you like me to work on?"
Step 4: Work loop
Important: Run all git and drupalorg commands from the project module directory.
Iterate until the pipeline is green or the user asks to stop:
- Make the requested code changes.
- If
vendor/bin/phpcs is available, run it on the module directory and fix any violations
before proceeding:
vendor/bin/phpcs <module-path>
Do not stage or commit files while PHPCS reports errors. Skip this step if PHPCS is
not installed.
- Before committing, inspect the project's commit style:
git log --oneline -5
Match the observed style (e.g. conventional commits, Issue #<nid> by <username>:, etc.)
rather than defaulting to any fixed template.
- Stage only the files you actually modified:
git add <specific-changed-files>
- Commit using the inferred message style:
git commit -m "<message matching project style>"
- Push:
git push
- Poll pipeline:
drupalorg mr:status <nid> <mr-iid> --format=llm
- If failing, fetch logs and fix:
drupalorg mr:logs <nid> <mr-iid>
[PAUSE] After each push, report the pipeline outcome and ask whether to continue
or stop.
Hand off for review (GitLab work items only): When the pipeline is green and the
user confirms the work is ready for review, flip the state label and unassign:
drupalorg issue:label <ref> state::needsReview
drupalorg issue:unassign <ref>
Notes
issue:setup-remote is idempotent — safe to re-run.--format=llm output is optimised for parsing; always use it when reading structured data.- If the fork has no branches, the contributor has not pushed yet — discuss with the user
before creating a new MR from the upstream project.
