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).