# Radicle Tekton Adapter

A CI adapter that bridges [Radicle CI Broker](https://seed.radicle.garden/rad:zwTxygwuz5LDGBq255RA2CbNGrz8) events to [Tekton Pipelines](https://tekton.dev/).

---

## What Does It Do?

The **radicle-tekton-adapter** receives Radicle CI events via stdin (JSON), matches them against routing rules, triggers Tekton pipelines via webhook, polls for status, and reports results back via stdout.

```
radicle-ci-broker (monitors Radicle events)
    ↓ (stdin: JSON event)
radicle-tekton-adapter (this component)
    ↓ (HTTP POST: trigger webhook)
Tekton EventListener
    ↓ (creates PipelineRun)
Tekton Pipeline
    ↓ (adapter polls for status)
radicle-tekton-adapter
    ↓ (stdout: JSON status)
radicle-ci-broker (reports back)
```

---

## Features

- ✅ **Event-driven** - Triggers pipelines based on git push, patches, tags
- ✅ **Flexible routing** - Route different events to different pipelines
- ✅ **Status reporting** - Real-time pipeline status back to broker
- ✅ **Kubernetes-native** - Works with Tekton's native resources
- ✅ **Configurable** - YAML-based routing rules

---

## Quick Start

### Build

```bash
# Build from source
cargo build --release

# Build Docker image
docker build -t radicle-tekton-adapter:latest .
```

### Configure

Create a configuration file:

```yaml
# config.yaml
tekton:
  webhook_url: "http://el-radicle-events.tekton-ci.svc.cluster.local:8080"
  api_url: "https://kubernetes.default.svc"
  namespace: "tekton-ci"
  dashboard_url: "https://ci.example.com"

rules:
  - name: "main-deploy"
    event_type: "push"
    branch_pattern: "^main$"
    pipeline: "build-and-deploy"
```

### Test

```bash
# Send a test event via stdin
echo '{
  "event_type": "push",
  "version": 1,
  "repository": {
    "id": "rad:z2u2CP1xPx7HgZ8u6HQHbRQjfBrjW",
    "name": "my-project"
  },
  "branch": "main",
  "after": "abc123"
}' | radicle-tekton-adapter --config config.yaml
```

Expected output (JSON on stdout):
```json
{"Triggered":{"run_id":"build-abc123","info_url":"https://..."}}
{"Finished":{"result":"Success"}}
```

---

## How It Works

### Input Protocol (stdin)

The adapter reads JSON events from stdin. Example:

```json
{
  "event_type": "push",
  "version": 1,
  "repository": {
    "id": "rad:z2u2CP1xPx7HgZ8u6HQHbRQjfBrjW",
    "name": "my-project",
    "description": "My project",
    "private": false,
    "default_branch": "main"
  },
  "pusher": {
    "id": "did:key:z6Mk...",
    "alias": "alice"
  },
  "branch": "main",
  "before": "abc123",
  "after": "def456",
  "commits": ["def456"]
}
```

### Output Protocol (stdout)

The adapter writes JSON status messages to stdout:

```json
{"Triggered":{"run_id":"build-abc123","info_url":"https://ci.example.com/..."}}
{"Running":{"status":"Running"}}
{"Finished":{"result":"Success"}}
```

### Routing Logic

1. **Receive event** from stdin
2. **Match against rules** (first match wins)
3. **Trigger webhook** (POST to Tekton EventListener)
4. **Poll for status** (query Tekton API)
5. **Report results** to stdout

---

## Configuration

### Supported Event Types

- **`push`** - Push to a branch
- **`patch`** - Patch created/updated/merged
- **`tag`** - Tag created

### Routing Rules

Rules are evaluated top-to-bottom. First match wins.

```yaml
rules:
  # Skip WIP branches
  - name: "skip-wip"
    event_type: "push"
    branch_pattern: "^wip/.*$"
    pipeline: "skip"
  
  # Deploy main branch
  - name: "main-deploy"
    event_type: "push"
    branch_pattern: "^main$"
    pipeline: "build-and-deploy"
    params:
      environment: "production"
  
  # Test feature branches
  - name: "feature-test"
    event_type: "push"
    branch_pattern: "^feature/.*$"
    pipeline: "test-suite"
  
  # Test patches
  - name: "patch-review"
    event_type: "patch"
    pipeline: "test-and-review"
```

See **[Configuration Reference](doc/configuration.md)** for complete documentation.

---

## Documentation

- **[Configuration Reference](doc/configuration.md)** - Complete configuration guide
- **[Architecture](ARCHITECTURE.md)** - How the adapter works internally
- **[Build Guide](BUILD.md)** - Build from source

---

## Integration

### With radicle-ci-broker

The broker calls this adapter when events occur. Configure the broker to use this adapter:

```yaml
# broker config.yaml
adapter: "/usr/local/bin/radicle-tekton-adapter"
adapter_env:
  RADICLE_TEKTON_ADAPTER_CONFIG: "/etc/radicle-tekton-adapter/config.yaml"

repos:
  - repo_id: "rad:z2u2CP1xPx7HgZ8u6HQHbRQjfBrjW"
    events:
      - push
      - patch
      - tag
```

### With Tekton

You need:
1. **Tekton Pipelines** installed
2. **EventListener** configured to accept webhooks
3. **Pipelines** defined (referenced in routing rules)

Example EventListener:

```yaml
apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: radicle-events
spec:
  serviceAccountName: tekton-triggers
  triggers:
    - name: radicle-trigger
      bindings:
        - ref: radicle-binding
      template:
        ref: radicle-template
```

---

## Docker Image

The Dockerfile builds a minimal Alpine-based image (~20MB) containing only the adapter binary.

```bash
# Build
docker build -t radicle-tekton-adapter:latest .

# Run
docker run --rm \
  -v /path/to/config.yaml:/etc/config.yaml \
  radicle-tekton-adapter:latest \
  --config /etc/config.yaml
```

---

## Development

### Build from Source

```bash
# Clone repository
git clone <repo-url>
cd radicle-tekton-adapter

# Build
cargo build --release

# Run tests
cargo test

# Run
./target/release/radicle-tekton-adapter --config config.yaml
```

### Project Structure

```
src/
├── main.rs       # Entry point and orchestration
├── config.rs     # Configuration loading
├── protocol.rs   # Stdin/stdout protocol
├── routing.rs    # Event-to-pipeline routing
├── tekton.rs     # Tekton API operations
└── io.rs         # I/O with broker
```

### Testing

```bash
# Run all tests
cargo test

# Run specific module tests
cargo test config::
cargo test routing::
cargo test protocol::

# Test with a real event
echo '{"event_type":"push",...}' | cargo run -- --config config.yaml
```

---

## Deployment

### Standalone

This adapter is a component that requires:
- **radicle-ci-broker** (calls the adapter)
- **Tekton Pipelines** (runs the CI/CD)

For a complete deployment solution, see the **radicle-tekton-ci** repository which provides a Helm chart deploying all components together.

### Kubernetes Example

The adapter typically runs as part of the radicle-ci-broker pod:

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: radicle-ci-broker
spec:
  containers:
  - name: broker
    image: radicle-ci-broker:latest
    command: ["/usr/local/bin/cib", "process-events"]
    env:
      - name: RADICLE_TEKTON_ADAPTER_CONFIG
        value: "/etc/adapter/config.yaml"
    volumeMounts:
      - name: adapter-config
        mountPath: /etc/adapter
  volumes:
    - name: adapter-config
      configMap:
        name: radicle-tekton-adapter-config
```

---

## Exit Codes

- `0` - Success (pipeline completed successfully)
- `1` - Failure (pipeline completed but failed)
- `2` - Error (pipeline could not run, or adapter error)

---

## Troubleshooting

### No pipeline triggered

Check logs (stderr) to see rule evaluation:
```
INFO: Received event type 'push' for branch 'main'
INFO: Evaluating rule 'main-deploy'
INFO: Rule matched, triggering pipeline 'build-and-deploy'
```

### Webhook fails

- Verify `webhook_url` is accessible
- Check EventListener is running: `kubectl get eventlistener -n tekton-ci`
- Test webhook manually:
```bash
curl -X POST http://el-radicle-events.tekton-ci.svc.cluster.local:8080 \
  -H "Content-Type: application/json" \
  -d '{"repo_id":"rad:z...","event_type":"push"}'
```

### Status polling fails

- Verify `api_url` is accessible
- Check RBAC permissions (needs `get`, `list` on PipelineRuns)
- Test API access: `kubectl get pipelineruns -n tekton-ci`

---

## Related Projects

- **[radicle-ci-broker](https://seed.radicle.garden/rad:zwTxygwuz5LDGBq255RA2CbNGrz8)** - Event dispatcher (calls this adapter)
- **[Tekton Pipelines](https://tekton.dev/)** - Kubernetes-native CI/CD
- **[Radicle](https://radicle.xyz/)** - Decentralized code collaboration

---

## Contributing

Contributions welcome! Submit patches to the Radicle repository.

---

## License

MIT License - See [LICENSE](LICENSE) file.

---

**Made with ❤️ for the decentralized web**