Skip to content
This repository was archived by the owner on Nov 24, 2025. It is now read-only.

Improve README docs #6

Open
bgandon wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Improve README docs #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 40 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
# concourse-keyval-resource
a [Concourse](https://concourse-ci.org/resources.html) resource for:
# Concourse Bloblang key-value resource

A [Concourse](https://concourse-ci.org/resources.html) resource for:

- passing arbitrary data between steps and/or jobs
- curating dynamic filesystem content

## Getting Started

```yaml
resource_types:
- name: keyval
Expand Down Expand Up @@ -35,9 +38,9 @@ jobs:
test.md: |
root = """
# Build Summary
| ID | Team | Pipeline | Job | Name |
| :---: | :--- | :--- | :--- | :--- |
| [%s](%s) | %s | %s | %s | %s |
| ID | Team | Pipeline | Job | Name |
| :------: | :--- | :------- | :--- | :--- |
| [%s](%s) | %s | %s | %s | %s |
""".format(id, url, team, pipeline, job, name)
test.json: |
uid = ksuid()
Expand Down Expand Up @@ -72,52 +75,60 @@ jobs:
## Configuration

**Parameters:**
| Parameter | Type | Description | Required |
| :--- | :---: | :--- | :---: |
| Parameter | Type | Description | Required |
| :-------- | :---: | :---------- | :------: |
| archive | [*archive.Archive](https://pkg.go.dev/github.com/cludden/concourse-go-sdk@v0.3.1/pkg/archive#Config) | optional archive config that can be used to enable [resource version archiving](https://github.com/cludden/concourse-go-sdk#archiving) | |
| initial_mapping | `string` | a [Bloblang mapping](https://www.benthos.dev/docs/guides/bloblang/about) that can be used to customize the initial version returned by this resource. See [Initial Mapping](#initial-mapping) for more details. | ⚠ |
| initial_mapping | `string` | a [Bloblang mapping][about_bloblang] that can be used to customize the initial version returned by this resource. See [Initial Mapping](#initial-mapping) for more details. | ⚠ |

## Behavior

### `check`

Check returns the latest available version produced by a `put` step. If `get` is used prior to `put`, an initial version will be returned which can be customized via the `initial_mapping` resource parameter.

### `in`

Fetches arbitrary key value data from a prior put step and writes it the file system as a JSON document.

**Parameters:**
| Parameter | Type | Description | Required |
| :--- | :---: | :--- | :---: |
| files | `map[string]string` | a map of filenames to [Bloblang mappings](https://www.benthos.dev/docs/guides/bloblang/about), where the input document contains the [build metadata](https://concourse-ci.org/implementing-resource-types.html#resource-metadata) along with any key value data from the fetched version, and the output is the content of the file to write (note: unless the file extension is one of `.json`, `.yaml`, or `.yml`, the mapping output must be of type `string` or `[]byte`) | |
| Parameter | Type | Description | Required |
| :-------- | :---: | :---------- | :------: |
| files | `map[string]string` | a map of filenames to [Bloblang mappings][about_bloblang], where the input document contains the [build metadata][resource_metadata] along with any key value data from the fetched version, and the output is the content of the file to write (note: unless the file extension is one of `.json`, `.yaml`, or `.yml`, the mapping output must be of type `string` or `[]byte`) | |

**Files:**
- `version.json` - the key value pairs serialized as a JSON document
- `metadata.json` - the [build metadata](https://concourse-ci.org/implementing-resource-types.html#resource-metadata) serialized as a JSON document
- `metadata.json` - the [build metadata][resource_metadata] serialized as a JSON document
- `*` any file mappings defined in the `files` parameter

### `out`

Publishes arbitrary key value data to be shared across jobs.

**Parameters:**
| Parameter | Type | Description | Required |
| :--- | :---: | :--- | :---: |
| mapping | `string` | a [Bloblang mappings](https://www.benthos.dev/docs/guides/bloblang/about), where the input document contains the [build metadata](https://concourse-ci.org/implementing-resource-types.html#resource-metadata), and the output is a `map[string]string`, defaults to `root = this` | |
| Parameter | Type | Description | Required |
| :-------- | :---: | :---------- | :------: |
| mapping | `string` | a [Bloblang mappings][about_bloblang], where the input document contains the [build metadata][resource_metadata], and the output is a `map[string]string`, defaults to `root = this` | |

[about_bloblang]: https://www.benthos.dev/docs/guides/bloblang/about
[resource_metadata]: https://concourse-ci.org/implementing-resource-types.html#resource-metadata

## Build Metadata
Each [Bloblang mappings](https://www.benthos.dev/docs/guides/bloblang/about) the following build metadata as input:
| Parameter | Type | Description | Always Available |
| :--- | :---: | :--- | :---: |
| build_created_by | `string` | the username that created the build, only available when the resource is configured to [expose_build_created_by](https://concourse-ci.org/resources.html#schema.resource.expose_build_created_by) | |
| build_id | `string` | the unique build identifier | ✓ |

Each [Bloblang mappings][about_bloblang] the following build metadata as input:
| Parameter | Type | Description | Always Available |
| :-------- | :---: | :---------- | :--------------: |
| build_created_by | `string` | the username that created the build, only available when the resource is configured to [expose_build_created_by](https://concourse-ci.org/resources.html#schema.resource.expose_build_created_by) | |
| build_id | `string` | the unique build identifier | ✓ |
| build_instance_vars | `string` | instance vars of the instanced pipeline that the build's job lives in, serialized as JSON | |
| build_job | `string` | the name of the job | ✓ |
| build_name | `string` | the build id in the context of the pipeline | ✓ |
| build_pipeline | `string` | the name of the pipeline | ✓ |
| build_team | `string` | the name of the team | ✓ |
| build_url | `string` | the fully qualified build url | ✓ |
| build_job | `string` | the name of the job | ✓ |
| build_name | `string` | the build id in the context of the pipeline | ✓ |
| build_pipeline | `string` | the name of the pipeline | ✓ |
| build_team | `string` | the name of the team | ✓ |
| build_url | `string` | the fully qualified build url | ✓ |

## Initial Mapping
In most sitautions, like the example below, the initial use of this resource is with a `put` step, followed by a later `get` step, in which case this field is not required and checking should be disabled via `check_every: never` to conserve resources.

In most situations, like the example below, the initial use of this resource is with a `put` step, followed by a later `get` step, in which case this field is not required and checking should be disabled via `check_every: never` to conserve resources.

```yaml
resource_types:
Expand All @@ -140,7 +151,7 @@ jobs:
params:
mapping: |
timestamp = now()

- name: second
plan:
- get: keyval
Expand Down Expand Up @@ -184,5 +195,6 @@ jobs:
```

## License
Licensed under the [MIT License](LICENSE.md)

Licensed under the [MIT License](LICENSE.md)
Copyright (c) 2023 Chris Ludden