tendril/docs/issues/archive/resolved/2025-11-11--gitea-runner-setup-request.md

# Gitea Actions Runner Configuration Request

**Type:** feature  
**Date:** 2025-11-11  
**Status:** resolved  
**Resolved:** 2025-11-11

---

## Description

We've just completed **Phase 3: Gitea Actions Workflows Setup** and have implemented two workflows:

1. **KB Lint Workflow** (`.github/workflows/kb-lint.yml`) - Validates KB file naming, frontmatter, and structure
2. **KB Index Update Workflow** (`.github/workflows/kb-index-update.yml`) - Auto-updates KB index on push to main

## Current Status

The workflows are properly configured and trigger correctly when KB files change. However, workflows are stuck in "Waiting" status because **no Gitea Actions runners are available** to execute them.

**Example**: We created a test KB file (`kb/01_projects/tendril/2025-11-11--test-kb-workflow--note.md`) to test the KB lint workflow. The workflow triggered correctly but has been waiting for over 3 minutes for a runner to become available.

## What We're Trying to Do

1. **Test KB Lint Workflow**: Validate that KB files follow naming conventions and frontmatter requirements
2. **Test KB Index Update Workflow**: Verify automatic index regeneration when KB files are added/modified
3. **Validate Phase 3 Implementation**: Confirm that Gitea Actions workflows are working correctly

## Request

Please configure Gitea Actions runners for the `Mycelium/tendril` repository so that workflows can execute.

### Required Runner Configuration

- **Platform**: `ubuntu-latest` (as specified in workflows)
- **Labels**: Should match `runs-on: ubuntu-latest` in workflow files
- **Repository**: `Mycelium/tendril`
- **Permissions**: 
  - KB Lint workflow needs `contents: read`
  - KB Index Update workflow needs `contents: write`

### Workflow Details

**KB Lint Workflow** (`.github/workflows/kb-lint.yml`):
- Triggers on: Push and pull requests when `kb/**/*.md` files change
- Purpose: Validates KB file naming pattern, frontmatter, and structure
- Permissions: `contents: read`

**KB Index Update Workflow** (`.github/workflows/kb-index-update.yml`):
- Triggers on: Push to `main` branch when `kb/**/*.md` files change
- Purpose: Automatically regenerates `kb/_index.md` when KB files are added/modified
- Permissions: `contents: write` (needs to commit and push index updates)

## Testing Plan

Once runners are configured, we will:

1. Verify KB lint workflow validates test file correctly
2. Test with invalid KB file to confirm validation catches errors
3. Test KB index update workflow on main branch
4. Clean up test file after validation

## References

- **Gitea Actions Documentation**: https://docs.gitea.com/usage/actions/
- **Gitea Runner Setup**: https://docs.gitea.com/usage/actions/runner/
- **Workflow Files**: 
  - `.github/workflows/kb-lint.yml`
  - `.github/workflows/kb-index-update.yml`
- **Project Documentation**: `docs/GITEA/Gitea-Actions-Guide.md`

## Additional Notes

- Workflows use standard GitHub Actions YAML format (Gitea Actions is compatible)
- All workflows are properly configured and trigger correctly
- The issue is solely that runners need to be registered/configured
- Test file will be deleted after workflow validation is complete

---

**Branch**: `docs/contributing-guide-and-workflow`  
**Related**: Phase 3 implementation, KB system setup

---

## Resolution

**Date:** 2025-11-11

### Status
✅ **RESOLVED** - Gitea Actions runners are now configured and workflows are executing successfully.

### Issues Found and Fixed

1. **Git Revision Error (Fixed)**
   - **Problem**: Workflow was using `HEAD~1...HEAD` which fails with shallow clones (depth=1)
   - **Error**: `fatal: bad revision 'HEAD~1...HEAD'`
   - **Solution**: Updated `.github/workflows/kb-lint.yml` to use `${{ github.event.before }}...${{ github.event.after }}` for push events, which works with shallow clones
   - **Location**: Line 38-39 in workflow file

2. **KB File Validation Errors (Expected)**
   - **Problem**: Test file `kb/01_projects/test/2025-11-11--runner-test--note.md` has validation errors
   - **Errors Found**:
     - Missing required fields: author, source, project, topics, type, status, routing_hint, proposed_path, routing_confidence, related, summary
     - Date mismatch: filename date (2025-11-11) vs frontmatter date (2025-01-14)
   - **Status**: This is expected behavior - the workflow is correctly catching validation errors
   - **Action**: Test file should be fixed or removed from the test branch

### Workflow Execution

- ✅ Runners are now available and executing workflows
- ✅ KB Lint workflow is running and validating files correctly
- ✅ Workflow correctly identifies validation errors in test files
- ✅ Git revision error has been resolved

### Changes Made

1. **Updated `.github/workflows/kb-lint.yml`**:
   - Changed push event file detection to use `github.event.before` and `github.event.after` instead of `HEAD~1...HEAD`
   - Added proper error suppression with `2>/dev/null`
   - Added fallback logic for edge cases (initial commits, force pushes)

### Next Steps

- Fix or remove the test file `kb/01_projects/test/2025-11-11--runner-test--note.md` if it's no longer needed
- **Merge workflow fix to test branch**: The fix is on `docs/contributing-guide-and-workflow` branch but needs to be merged to `test/runner-validation` branch (or merge to main first)
- Verify workflow runs successfully on next KB file change
- Consider adding workflow status badges to README

### Update: Test Results (2025-11-11 21:45)

**Status**: ⚠️ **Partial Success** - Workflow executes but error message still appears

**Test Branch**: `test/runner-validation`  
**Issue**: The workflow fix is on `docs/contributing-guide-and-workflow` branch, but the test is running on `test/runner-validation` branch which still has the old code.

**Current Behavior**:
- ✅ Workflow executes successfully
- ✅ Files are found and validated correctly
- ⚠️ Error message `fatal: bad revision 'HEAD~1...HEAD'` still appears in logs (but is suppressed)
- ✅ Validation works correctly (validates both valid and invalid files)

**Root Cause**: The `test/runner-validation` branch hasn't been updated with the workflow fix yet.

**Solution**: Merge the workflow fix from `docs/contributing-guide-and-workflow` to `test/runner-validation` (or merge to main first, then test branch will inherit it).