FictionArchive/Documentation/CICD.md

# CI/CD Configuration

This document describes the CI/CD pipeline configuration for FictionArchive using Gitea Actions.

## Workflows Overview

| Workflow | File | Trigger | Purpose |
|----------|------|---------|---------|
| CI | `build.yml` | Push/PR to master | Build and test all projects |
| Build Subgraphs | `build-subgraphs.yml` | Push to master (service changes) | Build GraphQL subgraph packages |
| Build Gateway | `build-gateway.yml` | Manual or triggered by subgraphs | Compose gateway and build Docker image |
| Release | `release.yml` | Tag `v*.*.*` | Build and push all Docker images |

## Pipeline Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                         Push to master                               │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│      build.yml          │     │   build-subgraphs.yml   │
│   (CI checks - always)  │     │  (if service changes)   │
└─────────────────────────┘     └────────────┬────────────┘
                                             │
                                             ▼
                                ┌─────────────────────────┐
                                │   build-gateway.yml     │
                                │  (compose & push API)   │
                                └─────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                        Push tag v*.*.*                               │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
                              ▼
                ┌─────────────────────────┐
                │      release.yml        │
                │  (build & push all)     │
                └─────────────────────────┘
```

## Required Configuration

### Repository Secrets

Configure these in **Settings → Actions → Secrets**:

| Secret | Description | Required By |
|--------|-------------|-------------|
| `REGISTRY_TOKEN` | Gitea access token with `write:package` scope | `release.yml`, `build-gateway.yml` |
| `GITEA_TOKEN` | Gitea access token for API calls | `build-subgraphs.yml` |

#### Creating Access Tokens

1. Go to **Settings → Applications → Access Tokens**
2. Create a new token with the following scopes:
   - `write:package` - Push container images
   - `write:repository` - Trigger workflows via API
3. Copy the token and add it as a repository secret

### Repository Variables

Configure these in **Settings → Actions → Variables**:

| Variable | Description | Example | Required By |
|----------|-------------|---------|-------------|
| `VITE_GRAPHQL_URI` | GraphQL API endpoint URL | `https://api.fictionarchive.example.com/graphql/` | `release.yml` |
| `VITE_OIDC_AUTHORITY` | OIDC provider authority URL | `https://auth.example.com/application/o/fiction-archive/` | `release.yml` |
| `VITE_OIDC_CLIENT_ID` | OIDC client identifier | `your-client-id` | `release.yml` |
| `VITE_OIDC_REDIRECT_URI` | Post-login redirect URL | `https://fictionarchive.example.com/` | `release.yml` |
| `VITE_OIDC_POST_LOGOUT_REDIRECT_URI` | Post-logout redirect URL | `https://fictionarchive.example.com/` | `release.yml` |

## Workflow Details

### CI (`build.yml`)

**Trigger:** Push or pull request to `master`

**Jobs:**
1. `build-backend` - Builds .NET solution and runs tests
2. `build-frontend` - Builds React application with linting

**Requirements:**
- .NET 8.0 SDK
- Python 3.12
- Node.js 20
- HotChocolate Fusion CLI

### Build Subgraphs (`build-subgraphs.yml`)

**Trigger:** Push to `master` with changes in:
- `FictionArchive.Service.*/**`
- `FictionArchive.Common/**`
- `FictionArchive.Service.Shared/**`

**Jobs:**
1. `build-subgraphs` - Matrix job building each service's `.fsp` package
2. `trigger-gateway` - Triggers gateway rebuild via API

**Subgraphs Built:**
- Novel Service
- Translation Service
- Scheduler Service
- User Service
- File Service

**Artifacts:** Each subgraph produces a `.fsp` file retained for 30 days.

### Build Gateway (`build-gateway.yml`)

**Trigger:**
- Manual dispatch (`workflow_dispatch`)
- Push to `master` with changes in `FictionArchive.API/**`
- Triggered by `build-subgraphs.yml` completion

**Process:**
1. Downloads all subgraph `.fsp` artifacts
2. Configures Docker-internal URLs for each subgraph
3. Composes gateway schema using Fusion CLI
4. Builds and pushes API Docker image

**Image Tags:**
- `<registry>/<owner>/fictionarchive-api:latest`
- `<registry>/<owner>/fictionarchive-api:<commit-sha>`

### Release (`release.yml`)

**Trigger:** Push tag matching `v*.*.*` (e.g., `v1.0.0`)

**Jobs:**
1. `build-and-push` - Matrix job building all backend service images
2. `build-frontend` - Builds and pushes frontend image

**Services Built:**
- `fictionarchive-api`
- `fictionarchive-novel-service`
- `fictionarchive-user-service`
- `fictionarchive-translation-service`
- `fictionarchive-file-service`
- `fictionarchive-scheduler-service`
- `fictionarchive-authentication-service`
- `fictionarchive-frontend`

**Image Tags:**
- `<registry>/<owner>/fictionarchive-<service>:<version>`
- `<registry>/<owner>/fictionarchive-<service>:latest`

## Container Registry

Images are pushed to the Gitea Container Registry at:
```
<gitea-server-url>/<repository-owner>/fictionarchive-<service>:<tag>
```

### Pulling Images

```bash
# Login to registry
docker login <gitea-server-url> -u <username> -p <token>

# Pull an image
docker pull <gitea-server-url>/<owner>/fictionarchive-api:latest
```

## Creating a Release

1. Ensure all changes are committed and pushed to `master`
2. Create and push a version tag:
   ```bash
   git tag v1.0.0
   git push origin v1.0.0
   ```
3. The release workflow will automatically build and push all images
4. Monitor progress in **Actions** tab

## Troubleshooting

### Build Failures

**"REGISTRY_TOKEN secret not found"**
- Ensure the `REGISTRY_TOKEN` secret is configured in repository settings
- Verify the token has `write:package` scope

**"Failed to trigger gateway workflow"**
- Ensure `GITEA_TOKEN` secret is configured
- Verify the token has `write:repository` scope

**"No subgraph artifacts found"**
- The gateway build requires subgraph artifacts from a previous `build-subgraphs` run
- Trigger `build-subgraphs.yml` manually or push a change to a service

### Frontend Build Failures

**"VITE_* variables are empty"**
- Ensure all required variables are configured in repository settings
- Variables use `vars.*` context, not `secrets.*`

### Docker Push Failures

**"unauthorized: authentication required"**
- Verify `REGISTRY_TOKEN` has correct permissions
- Check that the token hasn't expired

## Local Testing

To test workflows locally before pushing:

```bash
# Install act (GitHub Actions local runner)
# Note: act has partial Gitea Actions compatibility

# Run CI workflow
act push -W .gitea/workflows/build.yml

# Run with specific event
act push --eventpath .gitea/test-event.json
```