GitHub Actions Integration

Overview

The STRUKTD GitHub Action allows you to:

• Generate context on every commit or PR
• Attach context summaries to pull request comments
• Archive context for project documentation
• Trigger context generation on release tags
• Integrate with AI-powered code review workflows

Prerequisites

1. STRUKTD account (sign up at dashboard.struktd.com)
2. API key from your STRUKTD dashboard
3. GitHub repository with Actions enabled
4. Pro or Team tier for unlimited generations (recommended)

Step 1: Get Your API Key

1. Log in to dashboard.struktd.com
2. Navigate to Settings → API Keys
3. Click Generate New Key
4. Copy the key (it will only be shown once)
5. Give it a descriptive name like "GitHub Actions - MyRepo"

Step 2: Add API Key to GitHub Secrets

1. Go to your GitHub repository
2. Click Settings → Secrets and variables → Actions
3. Click New repository secret
4. Name: STRUKTD_API_KEY
5. Value: Paste your API key
6. Click Add secret

Step 3: Create Workflow File

Create .github/workflows/struktd-context.yml in your repository:

name: Generate Context with STRUKTD

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  generate-context:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        
      - name: Install STRUKTD CLI
        run: npm install -g @struktd/cli
        
      - name: Generate context
        env:
          STRUKTD_API_KEY: ${{ secrets.STRUKTD_API_KEY }}
        run: |
          struktd generate . \
            --output context.md \
            --format markdown
            
      - name: Upload context artifact
        uses: actions/upload-artifact@v4
        with:
          name: project-context
          path: context.md
          
      - name: Comment on PR (if applicable)
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const context = fs.readFileSync('context.md', 'utf8');
            
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '## 🤖 STRUKTD Context Generated\n\n' + 
                    '
View Project Context
\n\n' +
                    context + '\n\n
'
            });

Workflow Explanation

Triggers

• push - Runs on pushes to main/develop branches
• pull_request - Runs when PRs are opened to main

Steps

1. Checkout code: Checks out repository contents
2. Install STRUKTD: Installs CLI globally via npm
3. Generate context: Runs STRUKTD on current directory
4. Upload artifact: Saves context as workflow artifact
5. Comment on PR: Posts context summary to PR (optional)

Advanced Configurations

Generate on Release Tags

on:
  push:
    tags:
      - 'v*'

Exclude Directories

- name: Generate context
  run: |
    struktd generate . \
      --exclude "tests,docs,examples" \
      --output context.md

Multiple Output Formats

- name: Generate contexts
  run: |
    struktd generate . --format markdown --output context.md
    struktd generate . --format json --output context.json

Conditional Generation (Only on File Changes)

- name: Check for code changes
  id: changes
  uses: dorny/paths-filter@v2
  with:
    filters: |
      src:
        - 'src/**'
        - 'lib/**'

- name: Generate context
  if: steps.changes.outputs.src == 'true'
  run: struktd generate .

Use Cases

1. PR Review Assistant

Automatically provide context to reviewers on every pull request

on:
  pull_request:
    types: [opened, synchronize]

2. Release Documentation

Generate comprehensive context snapshots on releases

on:
  release:
    types: [published]
    
- name: Upload to release
  uses: softprops/action-gh-release@v1
  with:
    files: context.md

3. Continuous Context Archive

Build historical context library for project evolution

- name: Archive context with timestamp
  run: |
    DATE=$(date +%Y-%m-%d)
    mv context.md "context-$DATE.md"
    
- name: Commit to docs branch
  run: |
    git checkout -b docs
    git add *.md
    git commit -m "Context snapshot: $DATE"
    git push origin docs

Troubleshooting

Authentication Failed

Error: 401 Unauthorized

Solution:

• Verify API key is correctly set in GitHub Secrets
• Check key hasn't expired or been revoked
• Ensure secret name matches STRUKTD_API_KEY

Rate Limit Exceeded

Error: 429 Too Many Requests

Solution:

• Upgrade to Pro/Team tier for unlimited generations
• Reduce workflow trigger frequency
• Use conditional triggers (only on specific file changes)

CLI Installation Failed

Error: npm install fails

Solution:

• Check npm registry is accessible from Actions
• Use specific version: npm install -g @struktd/cli@1.0.0
• Cache node_modules for faster installs

Best Practices

• Use caching: Cache npm packages to speed up workflow
• Limit triggers: Only generate on significant changes
• Archive strategically: Don't commit every generation, archive milestones
• Protect secrets: Never expose API keys in logs or artifacts
• Set timeouts: Add workflow timeout to prevent hanging jobs
• Use matrix builds: Generate context for multiple branches/environments