# 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 Gateway | `build-gateway.yml` | Tag `v*.*.*` or manual | Build subgraphs, compose gateway, push API image |
| Release | `release.yml` | Tag `v*.*.*` | Build and push all Docker images |
| Claude PR Assistant | `claude_assistant.yml` | Issue/PR comments with @claude | AI-assisted code review and issue handling |

## Pipeline Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                         Push to master                               │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
                              ▼
                ┌─────────────────────────┐
                │      build.yml          │
                │     (CI checks)         │
                └─────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                        Push tag v*.*.*                               │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│      release.yml        │     │   build-gateway.yml     │
│  (build & push all      │     │  (build subgraphs &     │
│   backend + frontend)   │     │   push API gateway)     │
└─────────────────────────┘     └─────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│              Issue/PR comment containing @claude                     │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
                              ▼
                ┌─────────────────────────┐
                │  claude_assistant.yml   │
                │  (AI code assistance)   │
                └─────────────────────────┘
```

## 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` |
| `CLAUDE_CODE_OAUTH_TOKEN` | Claude Code OAuth token | `claude_assistant.yml` |
| `CLAUDE_GITEA_TOKEN` | Gitea token for Claude assistant | `claude_assistant.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` - For Claude assistant to push commits
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
- Node.js 20

**Steps (Backend):**
1. Checkout repository
2. Setup .NET 8.0
3. Restore dependencies
4. Build solution (Release, with `SkipFusionBuild=true`)
5. Run tests

**Steps (Frontend):**
1. Checkout repository
2. Setup Node.js 20
3. Install dependencies (`npm ci`)
4. Run linter (`npm run lint`)
5. Build application (`npm run build`)

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

**Trigger:**
- Manual dispatch (`workflow_dispatch`)
- Push tag matching `v*.*.*`

**Jobs:**

#### 1. `build-subgraphs` (Matrix Job)
Builds GraphQL subgraph packages for each service:

| Service | Project | Subgraph Name |
|---------|---------|---------------|
| novel-service | FictionArchive.Service.NovelService | Novel |
| translation-service | FictionArchive.Service.TranslationService | Translation |
| scheduler-service | FictionArchive.Service.SchedulerService | Scheduler |
| user-service | FictionArchive.Service.UserService | User |

**Note:** File Service and Authentication Service are not subgraphs (no GraphQL schema).

**Steps:**
1. Checkout repository
2. Setup .NET 8.0
3. Install HotChocolate Fusion CLI
4. Restore and build service project
5. Export GraphQL schema (`schema export`)
6. Pack subgraph into `.fsp` file
7. Upload artifact (retained 30 days)

#### 2. `build-gateway` (Depends on `build-subgraphs`)
Composes the API gateway from subgraph packages.

**Steps:**
1. Checkout repository
2. Setup .NET 8.0 and Fusion CLI
3. Download all subgraph artifacts
4. Configure Docker-internal URLs (`http://{service}-service:8080/graphql`)
5. Compose gateway schema using Fusion CLI
6. Build gateway project
7. Build and push 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)
Builds and pushes all backend service images:

| Service | Dockerfile |
|---------|------------|
| novel-service | FictionArchive.Service.NovelService/Dockerfile |
| user-service | FictionArchive.Service.UserService/Dockerfile |
| translation-service | FictionArchive.Service.TranslationService/Dockerfile |
| file-service | FictionArchive.Service.FileService/Dockerfile |
| scheduler-service | FictionArchive.Service.SchedulerService/Dockerfile |
| authentication-service | FictionArchive.Service.AuthenticationService/Dockerfile |

#### 2. `build-frontend`
Builds and pushes the frontend image with environment-specific build arguments.

**Build Args:**
- `VITE_GRAPHQL_URI`
- `VITE_OIDC_AUTHORITY`
- `VITE_OIDC_CLIENT_ID`
- `VITE_OIDC_REDIRECT_URI`
- `VITE_OIDC_POST_LOGOUT_REDIRECT_URI`

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

### Claude PR Assistant (`claude_assistant.yml`)

**Trigger:** Comments or issues containing `@claude`:
- Issue comments
- Pull request review comments
- Pull request reviews
- New issues (opened or assigned)

**Permissions Required:**
- `contents: write`
- `pull-requests: write`
- `issues: write`
- `id-token: write`

**Usage:**
Mention `@claude` in any issue or PR comment to invoke the AI assistant for:
- Code review assistance
- Bug analysis
- Implementation suggestions
- Documentation help

## Container Registry

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

### Image Naming Convention

| Image | Description |
|-------|-------------|
| `fictionarchive-api` | API Gateway (GraphQL Federation) |
| `fictionarchive-novel-service` | Novel Service |
| `fictionarchive-user-service` | User Service |
| `fictionarchive-translation-service` | Translation Service |
| `fictionarchive-file-service` | File Service |
| `fictionarchive-scheduler-service` | Scheduler Service |
| `fictionarchive-authentication-service` | Authentication Service |
| `fictionarchive-frontend` | Web Frontend |

### 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

**"No subgraph artifacts found"**
- The gateway build requires subgraph artifacts from the `build-subgraphs` job
- If subgraph builds failed, check the matrix job logs for errors

**"Schema export failed"**
- Ensure the service project has a valid `subgraph-config.json`
- Check that the service starts correctly for schema export

### 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

### Claude Assistant Failures

**"Claude assistant not responding"**
- Verify `CLAUDE_CODE_OAUTH_TOKEN` is configured
- Verify `CLAUDE_GITEA_TOKEN` is configured and has write permissions
- Check that the comment contains `@claude` mention

## 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
```