Add pipeline example and readme

README.md

@@ -1,15 +1,70 @@
 # tekton-caches [![build-test-publish](https://github.com/openshift-pipelines/tekton-caches/actions/workflows/latest.yaml/badge.svg)](https://github.com/openshift-pipelines/tekton-caches/actions/workflows/latest.yaml)
 
-Tools (and Task/StepAction) to managing within Tekton
-
-```bash
-# With OCI
-$ cache fetch --hasfiles '**/go.sum' --target oci://quay.io/vdemeest/cache/go-cache:{{hash}} --folder /workspaces/go-cache
-$ cache upload --hashfiles '**/go.sum' --target oci://quay.io/vdemeest/cache/go-cache:{{hash}} --folder /workspaces/go-cache
-# With s3
-$ cache fetch --hashfiles '**/go.sum' --target s3://my-bucket/path/to/my/cache --folder /workspaces/go-cache
-$ cache fetch --hashfiles '**/go.sum' --target s3://my-bucket/path/to/my/cache --folder /workspaces/go-cache
-# With gcs
-$ cache fetch --hashfiles '**/go.sum' --target gcs://my-bucket/path/to/my/cache --folder /workspaces/go-cache
-$ cache fetch --hashfiles '**/go.sum' --target gcs://my-bucket/path/to/my/cache --folder /workspaces/go-cache
+This is a tool to cache resources like go cache/maven or others on TektonCD
+pipelines.
+
+This tool supports uploading the cache to an OCI registry and plans to support
+S3, GCS and other storage backends.
+
+It uses the new [StepActions](https://tekton.dev/docs/pipelines/stepactions/)
+feature of TektonCD Pipelines but can be as well used without it.
+
+See the StepActions in the [tekton/](./tekton) directory.
+
+## Example
+
+This is an example of a build pipeline for a go application caching and reusing
+the go cache. If the `go.mod` and `go.sum` are changed the cache is invalidated and
+rebuilt.
+
+### Pre-requisites
+
+- You need a recent TektonCD pipelines installed with the StepActions feature-flags enabled.
+
+```shell
+kubectl patch configmap -n tekton-pipelines --type merge -p '{"data":{"enable-step-actions": "true"}}' feature-flags
 ```
+
+- A registry to push the images to. Example: docker.io/loginname. Make sure you
+  have setup tekton to be able to push/fetch from that registry, see the
+  [TektonCD pipelines documentation](https://tekton.dev/docs/pipelines/auth/#configuring-authentication-for-docker)
+
+### Usage
+
+Create the go pipeline example from the examples directory:
+
+```shell
+kubectl create -f pipeline-go.yaml
+```
+
+Start it with the tkn cli (change the value as needed):
+
+```shell
+tkn pipeline start pipeline-go --param repo_url=https://github.com/vdemeester/go-helloworld-app --param revision=main --param registry=docker.io/username -w name=source,emptyDir=
+```
+
+or with a PipelineRun yaml object:
+
+```shell
+```yaml
+kind: PipelineRun
+metadata:
+  name: build-go-application-with-caching-run
+spec:
+  pipelineRef:
+    name: pipeline-go
+  params:
+    - name: repo_url
+      value: https://github.com/vdemeester/go-helloworld-app
+    - name: revision
+      value: main
+    - name: registry
+      value: docker.io/username
+  workspaces:
+    - name: source
+      emptyDir: {}
+```
+
+## License
+
+[Apache License 2.0](./LICENSE)

examples/README.md

@@ -0,0 +1,51 @@
+# Examples
+
+This repository shows examples on how to use tekton-caches as stepactions
+
+## Pre-requisites
+
+- You need a recent TektonCD pipelines installed with the stepactions feature-flags enabled.
+
+```shell
+kubectl patch configmap -n tekton-pipelines --type merge -p '{"data":{"enable-step-actions": "true"}}' feature-flags
+```
+
+- A registry to push the images to. Example: docker.io/loginname. Make sure you
+  have setup tekton to be able to push/fetch from that registry, see the
+  [TektonCD pipelines documentation](https://tekton.dev/docs/pipelines/auth/#configuring-authentication-for-docker)
+
+## Usage
+
+Create the go pipeline example from the examples directory:
+
+```shell
+kubectl create -f pipeline-go.yaml
+```
+
+Start it with the tkn cli (change the value as needed):
+
+```shell
+tkn pipeline start pipeline-go --param repo_url=https://github.com/vdemeester/go-helloworld-app --param revision=main --param registry=docker.io/username -w name=source,emptyDir=
+```
+
+or with a PipelineRun yaml object:
+
+```shell
+```yaml
+kind: PipelineRun
+metadata:
+  name: build-go-application-with-caching-run
+spec:
+  pipelineRef:
+    name: pipeline-go
+  params:
+    - name: repo_url
+      value: https://github.com/vdemeester/go-helloworld-app
+    - name: revision
+      value: main
+    - name: registry
+      value: docker.io/username
+  workspaces:
+    - name: source
+      emptyDir: {}
+```

examples/pipeline-go.yaml

@@ -0,0 +1,88 @@
+---
+apiVersion: tekton.dev/v1
+kind: Pipeline
+metadata:
+  name: pipeline-go
+spec:
+  params:
+    - name: repo_url
+      type: string
+    - name: revision
+      type: string
+    - name: registry
+      type: string
+  workspaces:
+    - name: source
+  tasks:
+    - displayName: Build go application
+      name: noop-task
+      workspaces:
+        - name: source
+          workspace: source
+      taskSpec:
+        workspaces:
+          - name: source
+        steps:
+          - name: create-repo
+            image: cgr.dev/chainguard/go
+            script: |
+              mkdir -p $(workspaces.source.path)/repo
+              chmod 777 $(workspaces.source.path)/repo
+          - name: fetch-repo
+            ref:
+              resolver: http
+              params:
+                - name: url
+                  value: https://raw.githubusercontent.com/tektoncd/catalog/main/stepaction/git-clone/0.1/git-clone.yaml
+            params:
+              - name: output-path
+                value: $(workspaces.source.path)/repo
+              - name: url
+                value: $(params.repo_url)
+              - name: revision
+                value: $(params.revision)
+          - name: cache-fetch
+            ref:
+              resolver: http
+              params:
+                - name: url
+                  value: https://raw.githubusercontent.com/openshift-pipelines/tekton-caches/main/tekton/cache-fetch.yaml
+            params:
+              - name: patterns
+                value:
+                  - "**.go"
+                  - "**go.sum"
+              - name: source
+                value: oci://$(params.registry)/cache-go:{{hash}}
+              - name: cachePath
+                value: $(workspaces.source.path)/cache
+              - name: workingdir
+                value: $(workspaces.source.path)/repo
+          - image: cgr.dev/chainguard/go
+            workingDir: $(workspaces.source.path)/repo
+            name: noop-task
+            script: |
+              set -x
+              git config --global --add safe.directory $(workspaces.source.path)/repo
+              export GOCACHE=$(workspaces.source.path)/cache/gocache
+              export GOMODCACHE=$(workspaces.source.path)/cache/gomodcache
+              go build -v .
+              du -shk $GOPATH
+              du -shk $GOMODCACHE
+          - name: cache-upload
+            ref:
+              resolver: http
+              params:
+                - name: url
+                  value: https://raw.githubusercontent.com/openshift-pipelines/tekton-caches/main/tekton/cache-upload.yaml
+            params:
+              - name: patterns
+                value:
+                  - "**.go"
+                  - "**go.sum"
+              - name: target
+                value: oci://$(params.registry)/cache-go:{{hash}}
+              - name: cachePath
+                value: $(workspaces.source.path)/cache
+              - name: workingdir
+                value: $(workspaces.source.path)/repo

examples/pipelinerun.yaml

@@ -0,0 +1,18 @@
+---
+apiVersion: tekton.dev/v1
+kind: PipelineRun
+metadata:
+  name: build-go-application-with-caching-run
+spec:
+  pipelineRef:
+    name: build-go-application-with-caching
+  params:
+    - name: repo_url
+      value: https://github.com/vdemeester/go-helloworld-app
+    - name: revision
+      value: main
+    - name: registry
+      value: registry.civuole.local/cache
+  workspaces:
+    - name: source
+      emptyDir: {}