GitLab Usage

Copy of sumaris-pod/.agents/rules/gitlab.md (rule written for AI coding agents, when performing GitLab operations (issues, merge requests, branches, reviews)). Do not edit here: run npm run site:sync-rules to update it.

• Only access issues from the following projects:
  • sumaris-pod (ID: 1272)
  • sumaris-app (ID: 1273)

GitLab workflow rules

• For GitLab operations, prefer project-scoped actions on the current repository by default.
• Unless explicitly requested otherwise, assume the main GitLab project is the current project.
• Before creating or updating anything on GitLab, first summarize the intended action in one short sentence.
• When listing issues or merge requests, prefer concise output:
  • identifier;
  • title;
  • state;
  • labels;
  • milestone;
  • web link.
• When the user asks for "my issues", list issues assigned to the current authenticated user and restricted to opened issues by default.
• When the user asks for "MRs to review", list merge requests where the current authenticated user is reviewer and restricted to opened merge requests by default.
• When the user asks for merge requests assigned to a username, prefer reviewer-based interpretation only if the user says "to review"; otherwise use assignee-based interpretation.
• If a GitLab API filter fails because of incompatible parameters, retry with the smallest valid parameter set instead of changing the user intent.
• Never expose secrets, tokens, cookies, private URLs with credentials, or raw authentication headers in answers.
• Never copy sensitive configuration values from repository files into the response.
• Always use placeholders for secrets in examples.

Creating a branch from an issue

• When asked to create a branch from an issue, first retrieve the issue details and use:
  • the issue IID;
  • the issue title;
  • the project default branch unless the user specifies another source branch.
• Build the branch name from the issue using this convention:
  • issue/<iid>-<slug>
• The slug must:
  • be lowercase;
  • remove accents;
  • replace spaces and punctuation with -;
  • collapse repeated -;
  • be short but still understandable.
• Example:
  • issue #1783 Mensurations > Pas de recalcul des RTPs en temps réel
  • branch issue/1783-mensurations-recalcul-rtps
• After creating the branch, always return:
  • branch name;
  • source branch;
  • related issue link.

Preparing work from an issue

• If the user asks to work on an issue, the recommended order is:
  1. retrieve the issue;
  2. summarize the problem;
  3. identify likely code areas;
  4. create or select a working branch;
  5. only then propose code changes.
• If the issue description is ambiguous, ask one clarifying question before editing code.

Listing my issues

• "Mes tickets" means opened issues assigned to the current authenticated user unless the user asks for another state.
• Group results by milestone when that improves readability.
• If there are many results, provide:
  • a short summary count;
  • then the list.
• If labels suggest status conflicts like Done on an opened issue, mention it briefly.

Listing merge requests to review

• "Les MR que je dois reviewer" means opened merge requests where the current authenticated user is reviewer.
• Return for each merge request:
  • IID;
  • title;
  • source branch;
  • target branch;
  • author;
  • updated date;
  • web link.
• If there are no review MRs, say so explicitly.

Checking out the remote branch of a merge request

• If the user asks to checkout a merge request branch, first retrieve the merge request details and verify:
  • source branch;
  • target branch;
  • source project if available.
• If the merge request comes from the same repository, prefer checking out the source branch directly.
• If the merge request comes from a fork, clearly mention that the remote may need to be added or fetched before checkout.
• Before suggesting checkout commands, specify whether the branch is local already or remote only, if that information is available.
• Prefer safe command sequences that do not overwrite existing local work.
• Suggested flow:
  1. fetch the remote branch;
  2. create a local tracking branch if needed;
  3. checkout the local branch.
• Never suggest destructive git commands unless the user explicitly asks for them.

Creating a merge request

• Before creating a merge request, summarize:
  • source branch;
  • target branch;
  • title;
  • reviewers;
  • assignees;
  • draft status.
• Prefer a clear title format:
  • <scope>: <short summary>
  • or fix(<scope>): <short summary>
• The merge request description should contain when possible:
  • context;
  • changes made;
  • testing notes;
  • related issue reference.
• If there is a related issue, include a reference to it in the description.

Reviewing a merge request

• When asked to review a merge request, prefer this order:
  1. summary of intent;
  2. main changed files;
  3. risks or regressions;
  4. test impact;
  5. final review conclusion.
• Keep review comments actionable and specific.
• Prefer one comment per issue/theme instead of many tiny comments.
• If something is uncertain, mark it as a question, not as a defect.

Commenting on issues and merge requests

• Comments should be:
  • concise;
  • professional;
  • directly actionable.
• When proposing a fix in a comment, include:
  • observed problem;
  • expected behavior;
  • suggested direction.
• Avoid pasting long logs unless the user asks for full diagnostic output.

Safety rules for Git operations

• Before any branch creation, merge request creation, comment publication, approval, merge, or issue update, ask for confirmation if the user did not explicitly request the write action.
• Read-only actions do not need confirmation.
• Prefer non-destructive operations.
• If the repository state is unclear, say what assumption is being made.
• Do NOT use --trailer "Co-authored-by: ..." in git commit commands.