Skip to content

Commit a7f5352

Browse files
edaniszewskiedaniszewski
committed
docs: add initial README documentation
1 parent 40eed4c commit a7f5352

File tree

4 files changed

+177
-6
lines changed

4 files changed

+177
-6
lines changed

‎README.md‎

Lines changed: 172 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,174 @@
11
# chart-releaser
22

3-
CI tool for automatically updating Helm Charts on application release
3+
A CI tool to automate Helm Chart updates for new application releases.
4+
5+
This tool was developed to help make maintaining Helm Chart repos more sane. It works
6+
for a single Chart, or for repos holding multiple charts. By integrating the tool into
7+
CI pipelines, a new application release can trigger an automatic update to its corresponding
8+
Chart to update the appVersion and Chart version.
9+
10+
> **Note**: This tool is still in its infancy so there may be bugs, missing features,
11+
> non-ergonomic defaults, etc. If you have any questions, notice any issues, or have
12+
> suggestions for improvement, [open an issue](https://github.com/edaniszewski/chart-releaser/issues)
13+
> or open a PR - all contributions are welcome.
14+
15+
## Getting Started
16+
17+
### Getting
18+
19+
#### Latest
20+
21+
The latest release is available from the [releases](https://github.com/edaniszewski/chart-releaser/releases)
22+
page. All tags generate a release with pre-compiled binaries attached as assets.
23+
24+
#### Docker
25+
26+
A lightweight Docker image is also available:
27+
28+
```
29+
docker pull edaniszewski/chart-releaser
30+
```
31+
32+
#### Homebrew
33+
34+
macOS users can also install via [Homebrew](https://brew.sh/) by first adding the tap,
35+
then installing the package.
36+
37+
```
38+
brew tap edaniszewski/tap
39+
brew install chart-releaser
40+
```
41+
42+
### Running
43+
44+
`chart-releaser` can be run from the command line with no argument or with the `--help` flag
45+
to print usage info. The main entrypoint for kicking of a Chart update is through the `chart-releaese update`
46+
command.
47+
48+
It looks for a `.chartreleaser.yml` configuration file in the directory which it is run out of
49+
and executes an update based on those config options.
50+
51+
```
52+
chart-releaser update
53+
```
54+
55+
56+
## Configuring
57+
58+
`chart-releaser` is configured on a per-project basis, which usually translates to one config file
59+
for a repository. The config file should live in the repository for the application, not for the
60+
repository for its Helm Chart (assuming they are different).
61+
62+
The configuration is defined in a YAML-formatted file named`.chartreleaser.yml`.
63+
64+
Below is a description and examples of the different config options that are currently supported.
65+
66+
### v1
67+
68+
These configuration options apply to config files following the v1 schema, as denoted by the
69+
`version: v1` field in the configuration.
70+
71+
Note that in the tables below, a default value of `-` indicates no default and that the configuration
72+
is required.
73+
74+
#### Top Level Keys
75+
76+
Top-level keys for a `chart-releaser` configuration.
77+
78+
| Key | Description | Value |
79+
| --- | ----------- | ----- |
80+
| `version` | The version of the configuration scheme. This must be `v1` for v1 configs. | `-` |
81+
| `chart` | Defines where the Helm Chart exists for the configured project. | [Chart](#chart) |
82+
| `publish` | Defines how Chart/file updates should be published to the chart repo. | [Publish](#publish) |
83+
| `commit` | Defines the author of the commit(s) made to the chart repo. | [Commit](#commit) |
84+
| `release` | Defines behavior for how application releases are targeted and they affect the Chart version. | [Release](#release) |
85+
| `extras` | Defines any non-Chart.yaml files that should also be updated. | [Extras](#extras) |
86+
87+
#### Chart
88+
89+
> Defines where the Helm Chart exists for the configured project.
90+
91+
| Key | Description | Default |
92+
| --- | ----------- | ------- |
93+
| `name` | The name of the Chart. | `-` |
94+
| `repo` | The name of the repository holding the Chart for the project. This is required. It should follow the format `{{ RepoType }}/{{ Owner }}/{{ Name }}`. The currently supported repo types are: `github.com`. | `-` |
95+
| `path` | The sub-path to the chart in the repository. If this is empty, it assumes the Chart.yaml is in the root of the specified repository. | `""` |
96+
97+
#### Publish
98+
99+
> Defines how Chart/file updates should be published to the chart repo.
100+
101+
This defines a `commit` and `pr` key. If neither are specified, it defaults to "pr". Only one of
102+
the two keys may be specified at once.
103+
104+
`commit` commits directly to the configured branch, but will not open a PR. `pr` will commit to the
105+
configured branch and open a PR for the changes.
106+
107+
| Key | Description | Default |
108+
| --- | ----------- | ------- |
109+
| `commit.branch` | The name of the branch to commit to. | `master` |
110+
| `commit.base` | The base ref to create the new branch from. | `master` |
111+
| `pr.branch_template` | The name of the branch to commit to. This may be a template populated by update context. | `chartreleaser/{{ .Chart.Name }}/{{ .Chart.NewVersion }}` |
112+
| `pr.base` | The base ref to create the new branch from. | `master` |
113+
| `pr.title_template` | The title to use for the pull request. | see: [templates.go](./pkg/templates/templates.go) |
114+
| `pr.body_template` | The pull request body comment. | see: [templates.go](./pkg/templates/templates.go) |
115+
116+
#### Commit
117+
118+
> Defines the author of the commit(s) made to the chart repo.
119+
120+
| Key | Description | Default |
121+
| --- | ----------- | ------- |
122+
| `author.name` | Name of the commit author for published updates. | The git user name from gitconfig |
123+
| `author.email` | Email of the commit author for published updates. | The git user email from gitconfig |
124+
| `templates.update` | The template for the commit message to use on update. | see: [templates.go](./pkg/templates/templates.go) |
125+
126+
#### Release
127+
128+
> Defines behavior for how application releases are targeted and they affect the Chart version.
129+
130+
| Key | Description | Default |
131+
| --- | ----------- | ------- |
132+
| `matches` | A list of regex-compilable strings defining constraints that an application tag needs to meet to be eligible for chart-releaser update. | `[]` |
133+
| `ignores` | A list of regex-compilable strings defining constraints which prevent an application tag from being eligible for chart-releaser update. | `[]` |
134+
| `strategy` | The release strategy to use. See below for supported strategies. | `default` |
135+
136+
##### Strategies
137+
138+
The supported release strategies are:
139+
140+
* `default`: Bump the patch version of the Chart for any non-prerelease update to the app version. If the app has a prerelease bump, the chart version either gets a new prerelease suffix, or gets an existing prerelease suffix bumped.
141+
* `major`: Bump the major version of the Chart for any update to the app version.
142+
* `minor`: Bump the minor version of the Chart for any update to the app version.
143+
* `patch`: Bump the patch version of the Chart for any update to the app version.
144+
145+
#### Extras
146+
147+
> Defines any non-Chart.yaml files that should also be updated.
148+
149+
Extras as specified as a list, e.g.
150+
151+
```yaml
152+
extras:
153+
- path: some/path/to/README.md
154+
updates:
155+
- search: foo
156+
replace: bar
157+
limit: 1
158+
```
159+
160+
| Key | Description | Default |
161+
| --- | ----------- | ------- |
162+
| `path` | The path to the file to update, starting from the root of the charts repository. | `""` |
163+
| `updates[*].search` | A regex-compilable string defining the pattern that should be matched up for replacement within the file. | `-` |
164+
| `updates[*].replace` | The value to replace the found matches. This may be a template, which gets rendered with the update context. | `-` |
165+
| `updates[*].limit` | Limit the number of replaces to be performed in the file. A value of `0` indicates that there is no limit and all found matches should be replaced. | `0` |
166+
167+
#### Context
168+
169+
The `v1` config schema update context is used to render various templates in the configuration.
170+
See [context.go](./pkg/v1/ctx/context.go) for details on the fields provided by the context.
171+
172+
## License
173+
174+
`chart-releaser` is released under the [MIT License](LICENSE).

‎internal/testutils/client.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ func (c *FakeClient) GetFile(ctx context.Context, opts *client.Options, path str
3030
return c.FileData, data
3131
}
3232

33-
func (c *FakeClient) UpdateFile(ctx context.Context, opts *client.Options, path string, msg string, contents []byte) error {
33+
func (c *FakeClient) UpdateFile(ctx context.Context, opts *client.Options, path string, msg string, contents []byte) error {
3434
if len(c.UpdateFileError) == 0 {
3535
return nil
3636
}

‎pkg/v1/stages/config/config_test.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ func TestStage_Run(t *testing.T) {
7979

8080
// Release
8181
assert.Equal(t, "Bump {{ .Chart.Name }} Chart from {{ .Chart.PreviousVersion }} to {{ .Chart.NewVersion }}", context.Release.PRTitle)
82-
assert.Equal(t, "Bumps the {{ .Chart.Name }} Helm Chart from {{ .Chart.PreviousVersion }} to {{ .Chart.NewVersion }}.\n\n{{ if .Files }}The following files have also been updated:\n{{ range .Files }}- <pre>{{ .Path }}</pre>\n{{ end }}{{ end }}\n---\n*This PR was opened using [chart-releaser](https://github.com/edaniszewski/chart-releaser)*\n", context.Release.PRBody)
82+
assert.Equal(t, "Bumps the {{ .Chart.Name }} Helm Chart from {{ .Chart.PreviousVersion }} to {{ .Chart.NewVersion }}.\n\n{{ if .Files }}The following files have also been updated:\n{{ range .Files }}- {{ .Path }}\n{{ end }}{{ end }}\n---\n*This PR was generated with [chart-releaser](https://github.com/edaniszewski/chart-releaser)*\n", context.Release.PRBody)
8383
assert.Equal(t, "[{{ .Chart.Name }}] bump chart to {{ .Chart.NewVersion }} for new application release ({{ .App.NewVersion }})", context.Release.UpdateCommitMsg)
8484

8585
// Other

‎pkg/v1/stages/publish/publish_test.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -137,11 +137,11 @@ func TestStage_Run_StrategyPRDefaultTemplates(t *testing.T) {
137137
Bumps the test-chart Helm Chart from 1.2.2 to 1.2.3.
138138
139139
The following files have also been updated:
140-
- <pre>extra/file/1.txt</pre>
141-
- <pre>extra/file/2.txt</pre>
140+
- extra/file/1.txt
141+
- extra/file/2.txt
142142
143143
---
144-
*This PR was opened using [chart-releaser](https://github.com/edaniszewski/chart-releaser)*
144+
*This PR was generated with [chart-releaser](https://github.com/edaniszewski/chart-releaser)*
145145
`,
146146
), context.Release.PRBody)
147147
}

0 commit comments

Comments
 (0)