Setting Up ast-grep for Tekton Projects

Quick Setup

Use the automated setup script:

# In tektoncd/pipeline (or any Tekton project)
curl -O https://path-to/tekton-ast-grep-setup.sh  # Or copy from home repo
chmod +x tekton-ast-grep-setup.sh
./tekton-ast-grep-setup.sh .

Or manually copy from /tmp/tekton-ast-grep-setup.sh (generated from home repo).

What Gets Created

tektoncd/pipeline/
├── sgconfig.yml                    # Main configuration
├── .ast-grep/
│   ├── README.md                   # Usage guide
│   └── rules/
│       ├── go/
│       │   ├── wrap-errors.yml     # Error wrapping with %w
│       │   ├── no-error-discard.yml # Don't ignore errors
│       │   └── use-t-helper.yml    # t.Helper() in test helpers
│       └── yaml/
│           ├── tekton-use-v1.yml   # v1beta1 → v1 migration
│           ├── no-latest-tag.yml   # No :latest tags
│           ├── no-pipeline-resource.yml # Deprecated API
│           └── require-workspace.yml    # Use workspaces
├── Makefile.ast-grep              # Make targets
└── .github/workflows/
    └── ast-grep.yml               # CI integration

Starter Rules

Go Rules (3)

1. go-wrap-errors (warning)

Finds: return fmt.Errorf("failed: %v", err)
Fix:   return fmt.Errorf("failed: %w", err)

2. go-no-error-discard (error)

Finds: _, _ = client.Get(...)
Requires: Explicit error handling

3. go-use-t-helper (warning)

Finds: Test helper functions without t.Helper()
Ensures: Correct failure line numbers

YAML Rules (4)

1. tekton-use-v1-api (warning)

Finds: apiVersion: tekton.dev/v1beta1
Fix:   apiVersion: tekton.dev/v1

2. yaml-no-latest-tag (warning)

Finds: image: alpine:latest
Suggests: Use specific versions or digests

3. tekton-no-pipeline-resource (error)

Finds: kind: PipelineResource
Note: Deprecated in v1, use Tasks with workspaces

4. tekton-require-workspace (info)

Finds: Tasks without workspaces
Suggests: Use workspaces for data sharing

Usage

# Run full scan
ast-grep scan

# Show only errors
make lint-ast-grep-errors

# Get statistics
make lint-ast-grep-stats

# Scan specific area
ast-grep scan pkg/reconciler/

Expected Results on tektoncd/pipeline

Based on the repository structure (estimated):

Rule	Estimated Findings	Priority
tekton-use-v1-api	200-300	High (migration)
go-wrap-errors	50-100	Medium
go-no-error-discard	5-10	High (bugs)
yaml-no-latest-tag	10-20	Medium
tekton-require-workspace	30-50	Low (info)

Performance

Expected on tektoncd/pipeline (~2000 files):

Scan time: < 2 seconds
Memory: < 100MB
Fast enough for pre-commit and CI

Integration

Makefile

Add to main Makefile:

include Makefile.ast-grep

lint: lint-go lint-yaml lint-ast-grep

Pre-commit Hook

#!/usr/bin/env bash
set -euo pipefail

cd "$(git rev-parse --show-toplevel)"
if ast-grep scan --json 2>/dev/null | jq -e '.[] | select(.severity == "error")' >/dev/null; then
  echo "❌ ast-grep found errors"
  ast-grep scan --json | jq -r '.[] | select(.severity == "error")'
  exit 1
fi

GitHub Actions

Already included in .github/workflows/ast-grep.yml:

Runs on PR and push
Installs ast-grep
Scans codebase
Fails if errors found
Uploads results

Expansion Ideas

Additional Go Rules

go-context-propagation: Ensure context is passed through
go-require-rbac-markers: Controller methods need RBAC comments
go-no-direct-client-get: Use cached client
go-reconciler-pattern: Standard reconciler structure

Additional YAML Rules

tekton-timeout-set: Explicit timeouts
tekton-use-results: Tasks should declare results
tekton-no-privileged: Avoid privileged containers
k8s-deprecated-apis: Deprecated K8s APIs

Documentation Rules

go-require-doc-comment: Public functions need comments
yaml-require-description: CRDs need descriptions

Customization

Adjust Severity

Edit rule files to change severity:

severity: error   # Blocks CI
severity: warning # Shown but doesn't block
severity: info    # Informational only

Disable Rules

In sgconfig.yml:

# Disable specific rule
ignore:
  - rules/go/use-t-helper.yml

Or set severity to off in the rule file:

severity: off

Add Exceptions

Use not: clause in rules:

rule:
  pattern: problematic_pattern
  not:
    inside:
      pattern: acceptable_context

Rollout Strategy

Phase 1: Soft Launch (Week 1)

Install in tektoncd/pipeline
Run locally, don’t block CI
Gather feedback from maintainers
Adjust rules based on false positives

Phase 2: CI Integration (Week 2)

Enable GitHub Action
Start with warning severity only
Monitor for false positives
Fix clear violations

Phase 3: Enforcement (Week 3)

Upgrade critical rules to error
Block CI on errors
Pre-commit hook recommended
Document exceptions

Phase 4: Expansion (Week 4+)

Roll out to other tektoncd repos
Add more rules based on learnings
Community contributions
Shared rule repository

Success Criteria

< 5% false positive rate
Scan time < 5 seconds
Catches real issues in code review
Positive feedback from maintainers
Adopted by 3+ tektoncd repos
Community contributions

Troubleshooting

High false positive rate?

Adjust patterns in playground first
Add not: clauses for exceptions
Lower severity (error → warning → info)
Document known exceptions

Performance issues?

Use ignore: patterns for generated code
Scan specific directories
Run only critical rules in CI
Use --json and filter results

Conflicts with other linters?

ast-grep complements, doesn’t replace
Keep golangci-lint for Go semantics
Use ast-grep for Tekton-specific patterns
Layer tools: fast → comprehensive

Resources

Home implementation: ~/src/home/docs/code-analysis/
Tekton guide: ~/src/home/docs/code-analysis/ast-grep-tekton-guide.md
ast-grep docs: https://ast-grep.github.io/
Playground: https://ast-grep.github.io/playground.html
Tekton docs: https://tekton.dev/

Contributing

To add a rule:

Create .ast-grep/rules/<category>/<rule-name>.yml
Test locally: ast-grep scan --rule .ast-grep/rules/<category>/<rule-name>.yml
Test in playground: https://ast-grep.github.io/playground.html
Document in .ast-grep/README.md
Submit PR with examples
Iterate based on feedback

Next Steps

After setup:

Run initial scan: ast-grep scan | tee initial-scan.txt
Review findings: Identify false positives
Adjust rules: Fix patterns or severity
Create issues: For real violations found
Share results: With team for feedback
Iterate: Refine rules based on usage
Integrate: Add to CI when stable

Generated from: ~/src/home/docs/code-analysis/tekton-setup-guide.md
Setup script: /tmp/tekton-ast-grep-setup.sh
TODO: See org-mode TODO “Setup ast-grep for tektoncd projects”