# GitLab Issue Creation

## Objective

Create GitLab issues from app feedback and operational events in the chosen project.

A server-side path from an in-app report or system event to an issue in a configured GitLab project, on hosted or self-managed GitLab.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Make the GitLab host part of the connection, not a constant. Self-managed installations live on customer-controlled domains, so validate the host, its reachability, and the credential's scope at setup, and store both server-side only.
2. Let an administrator map the destination project along with labels, milestone, assignee, and whether the issue is created confidential. Default to confidential when the report may contain customer data, and make that default explicit rather than implied.
3. Compose the issue on the server from the originating record, a deep link back into the app, and the acting user's identity, redacting credentials and personal data from any attached log before it leaves the app.
4. Key each submission by the originating record so a retry after a timeout finds the existing issue instead of creating a second one, and store the returned issue reference for later status reconciliation.
5. GitHub Issue Creation, Linear Issue Creation, Jira Ticket Creation, Trello Card Creation, and Asana Task Creation are siblings. The capture, redaction, deduplication, and reference storage belong to a single shared path; this brief owns only the GitLab host handling, field mapping, and error translation.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- A self-managed host may sit behind a VPN, present an internal certificate, or run a version with different capabilities. Verify connectivity at setup, fail with a clear administrator-facing message, and do not assume the hosted service's behaviour applies.
- Labels, milestones, assignees, and the confidentiality flag must be selected from what the connected account can see in that project, and re-validated on use. A milestone closed or a label deleted since setup must not abort the submission; drop the unknown attribute, create the issue, and note what was dropped.
- Repeated submissions of the same report must converge on one issue. Fingerprint on the originating record or the error signature and comment on the existing issue rather than opening another.
- The project path, the host, and the token must never appear in client-side code, in an error message shown to a user, or in the issue body. A reporting user typically has no GitLab account at all and must not learn where private projects live.
- Projects get moved, renamed, transferred, or archived. Detect the redirect or the archived state, surface a configuration error to an administrator, and hold the queued reports rather than discarding them.
- Tokens expire and get revoked. Treat an authentication failure differently from a transient error: stop retrying, keep the submissions queued, and prompt an administrator to reconnect.
- Rate limits on hosted GitLab and on constrained self-managed instances require exponential backoff with jitter and a bounded retry count.
- When the GitLab instance is unreachable, accept the report in the app and create the issue later. The user sees their feedback recorded, not another organisation's outage.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] The GitLab host is configurable and validated at setup, covering hosted and self-managed installations.
- [ ] An administrator chooses the project, labels, milestone, assignee, and confidentiality, selected from what the connection can see.
- [ ] Duplicate or retried submissions resolve to the existing issue rather than a new one.
- [ ] Host, project path, and token never appear in client-side code, user-facing errors, or issue content.
- [ ] A moved or archived project raises an administrator-facing configuration error while queued reports are preserved.
- [ ] Authentication failures stop retries and prompt a reconnection instead of dropping submissions.
- [ ] An unreachable instance still records the report, which is created once the host returns.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.