GitLab Workflow & Branching Strategy

Repository Information

Branching Strategy

QR Igniter follows a modified GitFlow workflow optimized for continuous deployment.

main (protected)
  │
  ├── staging (protected)
  │     │
  │     └── production (protected)
  │
  ├── feature/QR-123-add-analytics-dashboard
  │
  ├── bugfix/QR-456-fix-gtin-validation
  │
  ├── hotfix/QR-789-critical-auth-fix
  │
  └── release/v2.1.0

Branch Types

Branch Workflow

# Create a new feature branch
git checkout main
git pull origin main
git checkout -b feature/QR-123-add-bulk-import

# Work on the feature...
git add .
git commit -m "feat(batch): add CSV bulk import functionality

- Add CsvImporter service for parsing CSV files
- Add validation for GTIN format in CSV
- Add batch creation endpoint

Closes #123"

# Push and create merge request
git push -u origin feature/QR-123-add-bulk-import
# Create MR in GitLab UI or use glab CLI

Commit Conventions

Conventional Commits

All commits must follow the Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Commit Types

Scope Examples

• api - REST API changes
• admin - Filament admin panel
• gs1 - GS1 Digital Link functionality
• qr - QR code generation
• analytics - Analytics features
• batch - Batch operations
• mobile - Flutter app
• docs - Documentation

Merge Requests

MR Requirements

• All CI/CD pipeline stages must pass
• At least 1 approval required
• All discussions must be resolved
• Branch must be up-to-date with target
• No merge conflicts

MR Template

## Description
Brief description of the changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issues
Closes #123

## Changes Made
- Change 1
- Change 2
- Change 3

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Documentation updated
- [ ] Tests pass locally
- [ ] No new warnings
- [ ] Accessibility reviewed (if UI changes)

## Screenshots (if applicable)
[Add screenshots here]

Code Review Guidelines

• Review within 24 hours
• Focus on logic, security, and maintainability
• Use constructive feedback
• Approve only when all concerns addressed

CI/CD Pipeline

Pipeline Stages

Pipeline Configuration

The pipeline is defined at the repository root in .gitlab-ci.yml. The application lives in backend/, so each job changes into that directory before running commands. Pipelines run automatically on merge requests and on pushes to main and develop; deploy jobs are manual.

# .gitlab-ci.yml  (root of repo — app lives in backend/)
stages:
  - quality
  - deploy

variables:
  COMPOSER_CACHE_DIR: "$CI_PROJECT_DIR/backend/.composer-cache"

# ── Quality gate (blocking) ──────────────────────────────────────────────────

lint:pint:
  stage: quality
  image: php:8.4-cli
  script:
    - cd backend
    - composer install --no-interaction --prefer-dist --quiet
    - ./vendor/bin/pint --test
  cache:
    key: composer-$CI_COMMIT_REF_SLUG
    paths:
      - backend/.composer-cache/
      - backend/vendor/
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'
    - if: '$CI_COMMIT_BRANCH == "develop"'

analyse:phpstan:
  stage: quality
  image: php:8.4-cli
  script:
    - cd backend
    - ./vendor/bin/phpstan analyse --level=5 --memory-limit=512M
  needs: [lint:pint]
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'
    - if: '$CI_COMMIT_BRANCH == "develop"'

test:coverage:
  stage: quality
  image: php:8.4-cli
  script:
    - cd backend
    - php artisan test --coverage --min=90
  coverage: '/Lines:\s*(\d+\.\d+)%/'
  artifacts:
    reports:
      junit: backend/storage/logs/junit.xml
      coverage_report:
        coverage_format: cobertura
        path: backend/coverage.xml
  needs: [analyse:phpstan]
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'
    - if: '$CI_COMMIT_BRANCH == "develop"'

security:audit:
  stage: quality
  image: php:8.4-cli
  script:
    - cd backend
    - composer audit
  needs: [lint:pint]
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'
    - if: '$CI_COMMIT_BRANCH == "develop"'

security:gitleaks:
  stage: quality
  image: zricethezav/gitleaks:latest
  script:
    - gitleaks detect --source . --exit-code 1
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'
    - if: '$CI_COMMIT_BRANCH == "develop"'

# ── Deploy (manual) ──────────────────────────────────────────────────────────

deploy:staging:
  stage: deploy
  script:
    - deploy_to_staging.sh
  environment:
    name: staging
    url: https://staging.qr2.ignited.cloud
  when: manual
  needs: [test:coverage, security:audit, security:gitleaks]
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
    - if: '$CI_COMMIT_BRANCH == "develop"'

deploy:production:
  stage: deploy
  script:
    - deploy_to_production.sh
  environment:
    name: production
    url: https://qr2.ignited.cloud
  when: manual
  needs: [deploy:staging]
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

Issue Management

Issue Labels

Issue Template

### Summary
A clear and concise description of the issue.

### Expected Behavior
What you expected to happen.

### Actual Behavior
What actually happened.

### Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. See error

### Environment
- Browser: [e.g., Chrome 120]
- OS: [e.g., macOS 14.0]
- Version: [e.g., v2.1.0]

### Additional Context
Any other context about the problem.

### Screenshots
If applicable, add screenshots.

AI-Assisted Development

AI Development Workflow

1. Issue Creation: Issues can be created by humans or AI from requirements
2. Branch Creation: AI creates feature branches following naming conventions
3. Development: AI writes code following project standards
4. Testing: AI writes tests meeting the ≥90% coverage floor enforced in CI
5. Code Review: Human reviews AI-generated code
6. Merge: Human approves and merges MR

AI Commit Attribution

AI-generated commits include attribution:

git commit -m "feat(api): add batch generation endpoint

- Add BatchController with generate action
- Add BatchRequest validation
- Add Batch API resource

Closes #456

Co-Authored-By: Claude Code <claude@anthropic.com>"

AI Development Guidelines

• All AI-generated code must be reviewed by a human
• AI commits must include Co-Authored-By attribution
• AI must follow all coding standards and conventions
• AI should not merge directly to protected branches
• Critical security code requires additional human review