Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
197f44b4d358b8c9fee52d299c783c0fb2671578
tendril/docs/issues/2025-11-11--gitea-runner-setup-request.md
Gitea Actions 197f44b4d3
Some checks failed
KB Lint / validate (push) Has been cancelled
Details
docs: add issues capture system and KB documentation 
This commit adds the issues capture system from PAIRS project and documents
it in the KB system, following all KB system rules for changelog and index
updates.

## What Was Added

### 1. Issues Capture System (docs/issues/)

**docs/issues/README.md** - System documentation:
- Purpose and workflow for quick issue capture
- File naming convention (YYYY-MM-DD--short-description.md)
- Issue types (bug, feature, insight, structural, improvement, question)
- Template fields and best practices
- Integration with Gitea platform
- Future automation possibilities

**docs/issues/template.md** - Issue file template:
- Minimal required fields (title, type, date, status)
- Optional fields (description, impact, notes, related)
- Gitea issue tracking section
- Simple, quick-capture format

**docs/issues/2025-11-11--gitea-runner-setup-request.md** - Moved from .github/:
- Gitea Actions runner configuration request
- Updated to match issue template format
- Includes type, date, status fields
- Ready for compilation to Gitea issue

### 2. KB Documentation Entry

**kb/02_systems/2025-11-11--issues-capture-system--note.md** - KB entry:
- Documents the issues capture system structure and workflow
- Explains quick capture process
- Describes compilation to Gitea issues
- Includes best practices and integration points
- Properly categorized in 02_systems/ (infrastructure/tooling)
- Complete frontmatter with all 18 required fields

### 3. KB System Updates

**kb/CHANGELOG.md** - Updated:
- Added entry for issues capture system documentation
- Date: 2025-11-11
- Documents KB file addition

**kb/_index.md** - Regenerated:
- Index updated via generate-index.sh script
- New KB file appears in 02_systems category
- Topics indexed: documentation, issue-tracking, workflow, gitea
- Tags indexed: issues, capture, documentation, gitea, workflow
- Summary updated with file count

## Why This Implementation

### Quick Issue Capture
   The issues capture system provides a lightweight staging area for capturing
   issues, insights, bugs, and features as you encounter them. This enables
   quick capture without the overhead of creating formal Gitea issues immediately.

### Markdown-Based Workflow
   Issues are captured as markdown files, making them easy to edit, version
   control, and review. This provides flexibility before committing to formal
   issue tracking.

### Later Compilation
   Issues can be batch-processed into Gitea issues when ready, allowing for
   review, prioritization, and grouping before creating formal issues.

### Documentation in KB
   The issues capture system is documented in the KB system, making it
   discoverable and providing reference material for the workflow.

## Technical Details

### File Structure

### Issue File Format

- **Naming**:
- **Template**: Minimal fields for quick capture
- **Status**: captured → reviewed → compiled
- **Integration**: Links to Gitea issues when compiled

### KB Entry Details

- **Category**: 02_systems (infrastructure, DevOps, tooling)
- **Type**: note
- **Topics**: documentation, issue-tracking, workflow, gitea
- **Tags**: issues, capture, documentation, gitea, workflow
- **Routing Confidence**: 0.95 (high confidence)

## Files Added/Modified

### Added
- docs/issues/README.md - Issues capture system documentation
- docs/issues/template.md - Issue file template
- docs/issues/2025-11-11--gitea-runner-setup-request.md - Runner setup request (moved from .github/)
- kb/02_systems/2025-11-11--issues-capture-system--note.md - KB documentation entry

### Modified
- kb/CHANGELOG.md - Added entry for new KB file
- kb/_index.md - Regenerated with new KB file indexed

## KB System Compliance

✅ KB file follows naming convention (YYYY-MM-DD--slug--type.md)
✅ KB file has complete frontmatter (all 18 required fields)
✅ KB file date matches filename date
✅ KB file type matches filename type
✅ KB changelog updated with entry
✅ KB index regenerated via script
✅ All changes committed together

## Related

- Source: PAIRS-for-the-Individual project (docs/issues/)
- KB System: kb/README.md
- KB Changelog: kb/CHANGELOG.md
- KB Index: kb/_index.md
- Gitea Documentation: docs/GITEA/
2025-11-11 12:31:15 -07:00

3.2 KiB
Raw Blame History

Gitea Actions Runner Configuration Request

Type: feature
Date: 2025-11-11
Status: captured

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

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

Reference in New Issue View Git Blame Copy Permalink