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

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

   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:

# 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