Skip to content

Commit 4e470f2

Browse files
taylorsilvataylorsilva
committed
update REDME to use tables instead of lists for all params
Used Claude 4.5 to convert the lists to tables and then verified that content was not changed. Signed-off-by: Taylor Silva <dev@taydev.net>
1 parent 2017457 commit 4e470f2

File tree

1 file changed

+197
-96
lines changed

1 file changed

+197
-96
lines changed

‎README.md‎

Lines changed: 197 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -12,70 +12,130 @@ Fetches and creates versioned GitHub resources.
1212
1313
## Source Configuration
1414

15-
* `owner`: *Required.* The GitHub user or organization name for the repository
16-
that the releases are in.
17-
18-
* `repository`: *Required.* The repository name that contains the releases.
19-
20-
* `access_token`: *Optional.* Used for accessing a release in a private-repo
21-
during an `in` and pushing a release to a repo during an `out`. The
22-
[fine-grained access
23-
token](https://github.com/settings/personal-access-tokens) you create is
24-
only required to have the `content` permission. For classic access tokens,
25-
you need the `repo` or `public_repo` permission.
26-
27-
* `github_api_url`: *Optional.* If you use a non-public GitHub deployment then
28-
you can set your API URL here.
29-
30-
* `github_v4_api_url`: *Optional.* If you use a non-public GitHub deployment then
31-
you can set your API URL for graphql calls here.
32-
33-
* `github_uploads_url`: *Optional.* Some GitHub instances have a separate URL
34-
for uploading. If `github_api_url` is set, this value defaults to the same
35-
value, but if you have your own endpoint, this field will override it.
36-
37-
* `insecure`: *Optional. Default `false`.* When set to `true`, concourse will allow
38-
insecure connection to your github API.
39-
40-
* `release`: *Optional. Default `true`.* When set to `true`, `check` detects
41-
final releases and `put` publishes final releases (as opposed to
42-
pre-releases). If `false`, `check` will ignore final releases, and `put` will
43-
publish pre-releases if `pre_release` is set to `true`
44-
45-
* `pre_release`: *Optional. Default `false`.* When set to `true`, `check`
46-
detects pre-releases, and `put` will produce pre-releases (if `release` is
47-
also set to `false`). If `false`, only non-prerelease releases will be detected
48-
and published.
49-
50-
**note:** if both `release` and `pre_release` are set to `true`, `put`
51-
produces final releases and `check` detects both pre-releases and releases. In
52-
order to produce pre-releases, you must set `pre_release` to `true` and
53-
`release` to `false`.
54-
**note:** if both `release` and `pre_release` are set to `false`, `put` will
55-
still produce final releases.
56-
**note:** releases must have [semver compliant](https://semver.org/#backusnaur-form-grammar-for-valid-semver-versions) tags to be detected.
57-
58-
* `drafts`: *Optional. Default `false`.* When set to `true`, `put` produces
59-
drafts and `check` only detects drafts. If `false`, only non-draft releases
60-
will be detected and published. Note that releases must have [semver compliant](https://semver.org/#backusnaur-form-grammar-for-valid-semver-versions)
61-
tags to be detected, even if they're drafts.
62-
63-
* `semver_constraint`: *Optional.* If set, constrain the returned semver tags according
64-
to a semver constraint, e.g. `"~1.2.x"`, `">= 1.2 < 3.0.0 || >= 4.2.3"`.
65-
Follows the rules outlined in https://github.com/Masterminds/semver#checking-version-constraints.
66-
67-
* `tag_filter`: *Optional.* If set, override default tag filter regular
68-
expression of `v?([^v].*)`. If the filter includes a capture group, the capture
69-
group is used as the release version; otherwise, the entire matching substring
70-
is used as the version.
71-
72-
* `order_by`: *Optional. One of [`version`, `time`]. Default `version`.*
73-
Selects whether to order releases by version (as extracted by `tag_filter`)
74-
or by time. See `check` behavior described below for details.
75-
76-
* `asset_dir`: *Optional. Default `false`.* When set to `true`, downloaded assets
77-
will be created in a separate directory called `assets`. Otherwise, they will be
78-
created in the same directory as the other files.
15+
<table>
16+
<thead>
17+
<tr>
18+
<th>Field Name</th>
19+
<th>Description</th>
20+
</tr>
21+
</thead>
22+
<tbody>
23+
<tr>
24+
<td><code>owner</code> (Required)</td>
25+
<td> The GitHub user or organization name for the repository that the releases are in.</td>
26+
</tr>
27+
<tr>
28+
<td><code>repository</code> (Required)</td>
29+
<td>The repository name that contains the releases.</td>
30+
</tr>
31+
<tr>
32+
<td><code>access_token</code> (Optional)</td>
33+
<td>
34+
Used for accessing a release in a private-repo during an <code>in</code> and pushing a
35+
release to a repo during an <code>out</code>. The
36+
<a href="https://github.com/settings/personal-access-tokens">fine-grained access token</a> you create is only
37+
required to have the <code>content</code> permission. For classic access tokens, you need the
38+
<code>repo</code> or <code>public_repo</code> permission.
39+
</td>
40+
</tr>
41+
<tr>
42+
<td><code>github_api_url</code> (Optional)</td>
43+
<td>If you use a non-public GitHub deployment then you can set your API URL here.</td>
44+
</tr>
45+
<tr>
46+
<td><code>github_v4_api_url</code> (Optional)</td>
47+
<td>
48+
If you use a non-public GitHub deployment then you can set your API URL for graphql calls
49+
here.
50+
</td>
51+
</tr>
52+
<tr>
53+
<td><code>github_uploads_url</code> (Optional)</td>
54+
<td>
55+
Some GitHub instances have a separate URL for uploading. If <code>github_api_url</code> is
56+
set, this value defaults to the same value, but if you have your own endpoint, this field will override it.
57+
</td>
58+
</tr>
59+
<tr>
60+
<td><code>insecure</code> (Optional)</td>
61+
<td>
62+
Defaults to <code>false</code>. When set to <code>true</code>, concourse will allow insecure
63+
connection to your github API.
64+
</td>
65+
</tr>
66+
<tr>
67+
<td><code>release</code> (Optional)</td>
68+
<td>
69+
Defaults to <code>true</code>. When set to <code>true</code>, <code>check</code> detects final
70+
releases and <code>put</code> publishes final releases (as opposed to pre-releases). If <code>false</code>,
71+
<code>check</code> will ignore final releases, and <code>put</code> will publish pre-releases if
72+
<code>pre_release</code> is set to <code>true</code>
73+
</td>
74+
</tr>
75+
<tr>
76+
<td><code>pre_release</code> (Optional)</td>
77+
<td>
78+
Defaults to <code>false</code>. When set to <code>true</code>, <code>check</code> detects
79+
pre-releases, and <code>put</code> will produce pre-releases (if <code>release</code> is also set to
80+
<code>false</code>). If <code>false</code>, only non-prerelease releases will be detected and published.
81+
<br/><br/>
82+
<strong>NOTE:</strong>
83+
If both <code>release</code> and <code>pre_release</code> are set to <code>true</code>,
84+
<code>put</code> produces final releases and <code>check</code> detects both pre-releases and releases. In order
85+
to produce pre-releases, you must set <code>pre_release</code> to <code>true</code> and <code>release</code> to
86+
<code>false</code>.<br /><strong>note:</strong> if both <code>release</code> and <code>pre_release</code> are
87+
set to <code>false</code>, <code>put</code> will still produce final releases.<br /><strong>note:</strong>
88+
releases must have
89+
<a href="https://semver.org/#backusnaur-form-grammar-for-valid-semver-versions">semver compliant</a>
90+
tags to be detected.
91+
</td>
92+
</tr>
93+
<tr>
94+
<td><code>drafts</code> (Optional)</td>
95+
<td>
96+
Defaults to <code>false</code>. When set to <code>true</code>, <code>put</code> produces drafts
97+
and <code>check</code> only detects drafts. If <code>false</code>, only non-draft releases will be detected and
98+
published. Note that releases must have
99+
<a href="https://semver.org/#backusnaur-form-grammar-for-valid-semver-versions">semver compliant</a>
100+
tags to be detected, even if they're drafts.
101+
</td>
102+
</tr>
103+
<tr>
104+
<td><code>semver_constraint</code> (Optional)</td>
105+
<td>
106+
If set, constrain the returned semver tags according to a semver constraint, e.g.
107+
<code>"~1.2.x"</code>, <code>">= 1.2 < 3.0.0 || >= 4.2.3"</code>. Follows the rules outlined in
108+
<a href="https://github.com/Masterminds/semver#checking-version-constraints"
109+
>https://github.com/Masterminds/semver#checking-version-constraints</a
110+
>.
111+
</td>
112+
</tr>
113+
<tr>
114+
<td><code>tag_filter</code> (Optional)</td>
115+
<td>
116+
If set, override default tag filter regular expression of <code>v?([^v].*)</code>. If the
117+
filter includes a capture group, the capture group is used as the release version; otherwise, the entire
118+
matching substring is used as the version. You can test your regex in the <a href="https://go.dev/play/p/shzMfC-rfI-">Go Playground</a>.
119+
</td>
120+
</tr>
121+
<tr>
122+
<td><code>order_by</code> (Optional)</td>
123+
<td>
124+
One of [<code>version</code>, <code>time</code>]. Defaults to <code>version</code>.
125+
Selects whether to order releases by version (as extracted by <code>tag_filter</code>) or by time. See
126+
<code>check</code> behavior described below for details.
127+
</td>
128+
</tr>
129+
<tr>
130+
<td><code>asset_dir</code> (Optional)</td>
131+
<td>
132+
Default <code>false</code>. When set to <code>true</code>, downloaded assets will be created
133+
in a separate directory called <code>assets</code>. Otherwise, they will be created in the same directory as the
134+
other files.
135+
</td>
136+
</tr>
137+
</tbody>
138+
</table>
79139

80140
### Example
81141

@@ -134,7 +194,7 @@ When sorting by time and a release is published, it uses the publication time, o
134194

135195
The returned list contains an object of the following format for each release (with timestamp in the RFC3339 format):
136196

137-
```
197+
```json
138198
{
139199
"id": "12345",
140200
"tag": "v1.2.3",
@@ -145,7 +205,7 @@ The returned list contains an object of the following format for each release (w
145205
When `check` is given such an object as the `version` parameter, it returns releases from the specified version or time on.
146206
Otherwise it returns the release with the latest version or time.
147207

148-
### `in`: Fetch assets from a release.
208+
### `get`: Fetch assets from a release.
149209

150210
Fetches artifacts from the requested release. If `asset_dir` source param is set to `true`,
151211
artifacts will be created in a subdirectory called `assets`.
@@ -161,43 +221,84 @@ Also creates the following files:
161221

162222
#### Parameters
163223

164-
* `globs`: *Optional.* A list of globs for files that will be downloaded from
165-
the release. If not specified, all assets will be fetched.
166-
167-
* `include_source_tarball`: *Optional.* Enables downloading of the source
168-
artifact tarball for the release as `source.tar.gz`. Defaults to `false`.
169-
170-
* `include_source_zip`: *Optional.* Enables downloading of the source
171-
artifact zip for the release as `source.zip`. Defaults to `false`.
172-
173-
### `out`: Publish a release.
224+
<table>
225+
<thead>
226+
<tr>
227+
<th>Field Name</th>
228+
<th>Description</th>
229+
</tr>
230+
</thead>
231+
<tbody>
232+
<tr>
233+
<td><code>globs</code> (Optional)</td>
234+
<td>A list of globs for files that will be downloaded from the release. If
235+
not specified, all assets will be fetched.</td>
236+
</tr>
237+
<tr>
238+
<td><code>include_source_tarball</code> (Optional)</td>
239+
<td>Enables downloading of the source artifact tarball for the release as
240+
<code>source.tar.gz</code>. Defaults to <code>false</code>.</td>
241+
</tr>
242+
<tr>
243+
<td><code>include_source_zip</code> (Optional)</td>
244+
<td>Enables downloading of the source artifact zip for the release as
245+
<code>source.zip</code>. Defaults to <code>false</code>.</td>
246+
</tr>
247+
</tbody>
248+
</table>
249+
250+
### `put`: Publish a release.
174251

175252
Given a name specified in `name`, a body specified in `body`, and the tag to use
176253
specified in `tag`, this creates a release on GitHub then uploads the files
177254
matching the patterns in `globs` to the release.
178255

179256
#### Parameters
180257

181-
* `name`: *Required.* A path to a file containing the name of the release.
182-
183-
* `tag`: *Required.* A path to a file containing the name of the Git tag to use
184-
for the release.
185-
186-
* `tag_prefix`: *Optional.* If specified, the tag read from the file will be
187-
prepended with this string. This is useful for adding v in front of version numbers.
188-
189-
* `commitish`: *Optional.* A path to a file containing the commitish (SHA, tag,
190-
branch name) that the release should be associated with.
191-
192-
* `body`: *Optional.* A path to a file containing the body text of the release.
193-
194-
* `globs`: *Optional.* A list of globs for files that will be uploaded alongside
195-
the created release.
196-
197-
* `generate_release_notes`: *Optional.* Causes GitHub to autogenerate the release notes
198-
when creating a new release, based on the commits since the last release.
199-
If `body` is specified, the body will be pre-pended to the automatically generated
200-
notes. Has no effect when updating an existing release. Defaults to `false`.
258+
<table>
259+
<thead>
260+
<tr>
261+
<th>Field Name</th>
262+
<th>Description</th>
263+
</tr>
264+
</thead>
265+
<tbody>
266+
<tr>
267+
<td><code>name</code> (Required)</td>
268+
<td>A path to a file containing the name of the release.</td>
269+
</tr>
270+
<tr>
271+
<td><code>tag</code> (Required)</td>
272+
<td>A path to a file containing the name of the Git tag to use for the release.</td>
273+
</tr>
274+
<tr>
275+
<td><code>tag_prefix</code> (Optional)</td>
276+
<td>If specified, the tag read from the file will be prepended with this
277+
string. This is useful for adding v in front of version numbers.</td>
278+
</tr>
279+
<tr>
280+
<td><code>commitish</code> (Optional)</td>
281+
<td>A path to a file containing the commitish (SHA, tag, branch name) that
282+
the release should be associated with.</td>
283+
</tr>
284+
<tr>
285+
<td><code>body</code> (Optional)</td>
286+
<td>A path to a file containing the body text of the release.</td>
287+
</tr>
288+
<tr>
289+
<td><code>globs</code> (Optional)</td>
290+
<td>A list of globs for files that will be uploaded alongside the created release.</td>
291+
</tr>
292+
<tr>
293+
<td><code>generate_release_notes</code> (Optional)</td>
294+
<td>Causes GitHub to autogenerate the release notes when creating a new
295+
release, based on the commits since the last release. If <code>body</code>
296+
is specified, the body will be pre-pended to the automatically generated
297+
notes. Has no effect when updating an existing release. Defaults to
298+
<code>false</code>.</td>
299+
</tr>
300+
</tbody>
301+
</table>
201302

202303
## Development
203304

0 commit comments

Comments
 (0)