# Decisions — .github Directory

_Last updated: 2025-01-27_

## Purpose

This document tracks decisions made about Gitea Actions workflows, automation, and the .github directory structure. Decisions are documented with context, rationale, and alternatives considered.

---

## Decision Format

Each decision entry includes:
- **Date**: When the decision was made
- **Context**: What problem or need prompted this decision
- **Decision**: What was decided
- **Rationale**: Why this approach was chosen
- **Alternatives**: Other options considered
- **Impact**: What this affects

---

## Decisions

### [2025-01-27] Use Gitea Actions (not GitHub Actions)

**Context**: Repository is hosted on Gitea platform (self-hosted), not GitHub. Need to configure CI/CD automation for repository maintenance.

**Decision**: Use Gitea Actions with GitHub Actions compatibility.

**Rationale**:
- Gitea Actions uses the same YAML format as GitHub Actions
- Workflows are compatible and can be migrated seamlessly
- Same `.github/workflows/` directory structure
- Familiar syntax for developers
- No need to learn a different workflow system

**Alternatives Considered**:
- Use GitHub Actions (not possible - repository is on Gitea)
- Use external CI/CD service (adds complexity, external dependency)
- Manual automation (not scalable, error-prone)

**Impact**:
- All workflows use `.github/workflows/` structure
- Workflows use standard GitHub Actions YAML format
- Documentation references "Gitea Actions" with compatibility notes
- Workflows can be tested and run on Gitea platform

---

### [2025-01-27] Automate KB Index Updates

**Context**: KB index (`kb/_index.md`) must stay current with KB files. Manual updates are error-prone and easy to forget.

**Decision**: Auto-update index on push to main branch when KB files change.

**Rationale**:
- Reduces manual maintenance burden
- Ensures index always reflects current KB state
- Prevents index from becoming stale
- Automated process is more reliable than manual updates
- Index generation script already exists and works

**Alternatives Considered**:
- Manual index updates (error-prone, easy to forget)
- Update on every push (too frequent, unnecessary commits)
- Scheduled updates (may miss recent changes)

**Impact**:
- Index is automatically updated when KB files are added/modified on main
- Requires `contents: write` permission for workflow
- Creates automatic commits with index updates
- Index always reflects current KB state

---

### [2025-01-27] Validate KB Files in CI

**Context**: KB files must follow strict naming and frontmatter rules. Invalid files break the KB system and cause index generation to fail.

**Decision**: Validate KB files on push and pull requests when KB files change.

**Rationale**:
- Catch errors early before they reach main branch
- Maintain KB system integrity
- Prevent invalid files from breaking index generation
- Provide clear error messages for developers
- Enforce KB file standards automatically

**Alternatives Considered**:
- Manual validation (error-prone, easy to miss)
- Validate only on main branch (errors caught too late)
- No validation (system breaks with invalid files)

**Impact**:
- Invalid KB files block commits
- Developers get immediate feedback on errors
- KB system maintains high quality standards
- Requires `contents: read` permission for workflow

---

## Future Decisions

Decisions about new workflows, automation changes, or .github structure modifications should be added here with the same format.

---

**Location**: `.github/decisions.md`  
**Maintained by**: Tendril Project Team