# Pysae CI/CD Conventions

## Shared templates

Source: `pysae/infra/gitlab-templates` (branch `2.x`)

Templates are included in each repo's `.gitlab-ci.yml` via:
```yaml
include:
  - project: 'pysae/infra/gitlab-templates'
    ref: '2.x'
    file: '/templates/<template-name>.yml'
```

### Template rules
- Templates **must NOT define** `stage:` or `allow_failure:` — each project manages its own pipeline orchestration
- Each project sets `stage:` and `allow_failure:` explicitly on the job

## Standard stages (typical order)

```yaml
stages:
  - check       # lint, SAST, audit
  - test        # unit tests, integration tests
  - build       # compile, docker build
  - deploy      # deploy to env (dev/integ/prod)
  - release     # tag, changelog, store upload
```

Not all repos use all stages. Order may vary.

## Default branch

**All Pysae repos use `main`** as the default branch. `develop` is legacy/obsolete — never target it.

## Common CI/CD variables

| Variable | Scope | Usage |
|----------|-------|-------|
| `CI_JOB_TOKEN` | Auto | GitLab registry, API calls within pipeline |
| `PYSAE_NPM_AUTH_TOKEN` | op, editor | Private npm registry access |
| `GITLAB_TOKEN` | Group | Cross-repo API calls (glab) |
| `DD_API_KEY` | Group | Datadog monitoring |
| `SONAR_TOKEN` | Per repo | SonarQube (if enabled) |

## Docker images

| Repo | CI Image |
|------|----------|
| driver | `registry.gitlab.com/pysae/infra/docker-images/yarn-android:python-jod-platform-35` |
| op, info, editor, screen | Node-based (check `.gitlab-ci.yml`) |
| api, prefect | Python-based (check `.gitlab-ci.yml`) |
| gtfsrt-to-siri | Node 20 |

## Semgrep (SAST)

Repos using Semgrep template: `op`, `gtfs-validator`, `prefect`, `screen`, `editor`

Each must explicitly set:
```yaml
sast:
  stage: check
  allow_failure: true
```

## Release workflow

Standard pattern across repos:
1. MR merged to `main`
2. Manual or auto trigger of release job
3. Tag created (semver: `vX.Y.Z`)
4. Changelog generated from MR titles
5. Pipeline triggered on tag → build + deploy

### Mobile-specific (driver / info)
- Driver: APK built per flavor (`.main`, `.enterprise`)
- Info: iOS archive + TestFlight upload (Mac runner required)
- Both: version bump in `package.json` + native config files

## Repo-specific quirks

### api (Python/FastAPI)
- Uses `alembic` for DB migrations — migration failures may cascade
- `pytest` with PostgreSQL test DB — needs `DATABASE_URL` in CI

### op (Vue 3)
- Orval codegen from API OpenAPI spec — type mismatches when API spec changes
- `yarn npm audit` requires `PYSAE_NPM_AUTH_TOKEN`

### driver (Capacitor/Android)
- Android signing keys configured per flavor
- Package name includes `.v5` (legacy — migration to v6 in progress)
- Gradle build can be slow — watch for timeout

### gtfsrt-to-siri (Node/Fastify)
- 354+ tests (Vitest) — fast but many
- Signed commits required — clone must be under `~/work/pysae/`

### infra repos
- Terraform plan/apply in CI — never auto-apply to prod
- Helm chart linting in CI
