Skip to content

Commit 0fc8119

Browse files
jimschubertjimschubert
committed
doc: Create README for action
1 parent 426dbf4 commit 0fc8119

File tree

1 file changed

+321
-0
lines changed

1 file changed

+321
-0
lines changed

‎README.md‎

Lines changed: 321 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,323 @@
11
# Beast Changelog Action
22

3+
> This changelog action is a beast :)
4+
5+
Maybe not entirely true. This action aims to do a few things:
6+
7+
* Give credit where credit is due by linking to pull request author profiles
8+
* Differentiate between direct commits and pull requests
9+
* Ignore merge commits
10+
* Allow for template-based customization of outputs (for example if you target AsciiDoc rather than Markdown)
11+
* Group (and optionally exclude) commits from the changelog based on patterns
12+
* Don't assume tag formats or anything else, just operate linearly _from_ one hash and _to_ another
13+
14+
_Beast Changelog Action_ is built on top of [jimschubert/changelog](https://github.com/jimschubert/changelog), which could be wrapped similarly to this action if you need to target another CI tool.
15+
16+
## Inputs
17+
18+
### `GITHUB_TOKEN`
19+
20+
**Required** Default: `${{github.token}}`
21+
22+
GitHub token used to access the repository defined in the GITHUB_REPOSITORY input.
23+
24+
It is recommended to [create a new personal access token](https://github.com/settings/tokens/new) with the least permissions (e.g. public_repo).
25+
Using a service account for the GitHub Token is also highly recommended.
26+
27+
[Learn more about using secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
28+
29+
### `GITHUB_REPOSITORY`
30+
31+
**Required** Default: `${{github.repository}}`
32+
33+
The target github repo in the format owner/repo
34+
35+
### `CONFIG_LOCATION`
36+
37+
**Required** Default: `.github/changelog.json`
38+
39+
The file location to the changelog configuration.
40+
41+
See [jimschubert/changelog](https://github.com/jimschubert/changelog) for schema and further details.
42+
43+
### `OUTPUT`
44+
45+
**Required** Default: `.github/CHANGELOG.md`
46+
47+
The output file where the changelog will be written.
48+
49+
The file is created and appended, but _not_ committed back to the repository.
50+
51+
It is recommended to add a post-processing step in your workflow to prepend to an existing changelog.
52+
53+
### `FROM`
54+
55+
**Required**
56+
57+
The beginning tag from which to generate the changelog.
58+
59+
This can be queried on an unshallow-ed repository with:
60+
61+
```
62+
git describe --tags --abbrev=0 --match 'v*' HEAD~
63+
```
64+
65+
See also [jimschubert/query-tag-action](https://github.com/jimschubert/query-tag-action).
66+
67+
### `TO`
68+
69+
**Required**
70+
71+
The ending tag until which the changelog should be generated.
72+
73+
This can be queried on an unshallow-ed repository with:
74+
75+
```
76+
git describe --tags --abbrev=0 --match 'v*' HEAD
77+
```
78+
79+
See also [jimschubert/query-tag-action](https://github.com/jimschubert/query-tag-action).
80+
81+
## Outputs
82+
83+
The action itself does not output any arguments. Your settings _may_ result in an artifact carried between steps.
84+
85+
## Usage
86+
87+
### Define `.github/changelog.json`
88+
89+
This action supports JSON and YAML 1.1 configuration files, but defaults to JSON.
90+
91+
The schema is as follows:
92+
93+
```json5
94+
{
95+
// "commits" or "prs", defaults to commits. "prs" will soon allow for resolving labels
96+
// from pull requests
97+
"resolve": "commits",
98+
99+
// "asc" or "desc", determines the order of commits in the output
100+
"sort": "asc",
101+
102+
// GitHub user or org name
103+
"owner": "jimschubert",
104+
105+
// Repository name
106+
"repo": "changelog",
107+
108+
// Enterprise GitHub base url
109+
"enterprise": "https://ghe.example.com",
110+
111+
// Path to custom template following Go Text template syntax
112+
"template": "/path/to/your/template",
113+
114+
// Group commits by headings based on patterns supporting Perl syntax regex or plain text
115+
"groupings": [
116+
{ "name": "Contributions", "patterns": [ "(?i)\\bfeat\\b" ] }
117+
],
118+
119+
// Exclude commits based on this set of patterns or texts
120+
// (useful for common maintenance commit messages)
121+
"exclude": [
122+
"^(?i)release\\s+\\d+\\.\\d+\\.\\d+",
123+
"^(?i)minor fix\\b",
124+
"^(?i)wip\\b"
125+
],
126+
127+
// Prefers local commits over API. Requires executing from within a Git repository.
128+
"local": false,
129+
130+
// Processes UP TO this many commits before processing exclusion/inclusion rules. Defaults to size returned from GitHub API.
131+
"max_commits": 250
132+
}
133+
```
134+
135+
Regex patterns for groupings and exclusions must be escaped according to the [ECMA-404 JSON Data Interchange Syntax](https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf) specification.
136+
137+
An example YAML file might look like:
138+
139+
```yaml
140+
%YAML 1.1
141+
---
142+
resolve: commits
143+
owner: jimschubert
144+
repo: ossify
145+
groupings:
146+
- name: feature
147+
patterns: ['^a','\bb$']
148+
- name: bug
149+
patterns: ['cba','\b\[f\]\b']
150+
exclude:
151+
- wip
152+
- help wanted
153+
enterprise: 'https://ghe.example.com'
154+
template: /path/to/template
155+
sort: asc
156+
max_commits: 199
157+
local: true
158+
```
159+
160+
### Create a workflow
161+
162+
A [full example](.github/workflows/example.yml) is available in this repository.
163+
164+
At a minimum, your workflow _must_:
165+
166+
* Checkout the git repository (e.g. via `actions/checkout@v2`)
167+
* Unshallow the git repository
168+
* Query an earlier tag
169+
* Query the later tag
170+
* Include the Beast Changelog Action
171+
172+
#### Unshallow
173+
174+
GitHub Actions create a [shallow](https://www.git-scm.com/docs/shallow) clone by default. This reduces traffic and handles most build-related use cases.
175+
176+
We need to "unshallow" the repository in order to access tag information. *If you forget to unshallow, the changelog step will fail.*
177+
178+
To unshallow, simply run `git fetch --prune --unshallow`
179+
180+
#### Query the **FROM** Tag
181+
182+
It doesn't really matter how you query the starting tag. This value could be hard-coded and updated manually, pulled via GitHub's Releases API, or queried via rules as an individual step.
183+
184+
The example in this repository uses one of my other actions, [jimschubert/query-tag-action@v1](https://github.com/jimschubert/query-tag-action), to accept some tag rules and output the found tag:
185+
186+
```yaml
187+
- name: Find Last Tag
188+
id: last
189+
uses: jimschubert/query-tag-action@v1
190+
with:
191+
include: 'v*'
192+
exclude: '*-rc*'
193+
commit-ish: 'HEAD~'
194+
skip-unshallow: 'true'
195+
```
196+
197+
This action will output the found tag (or fail if no tag is found). It can later be referenced according to the `id` as `${{steps.last.outputs.tag}}`.
198+
199+
The above query-tag-action example is simply a wrapper around the command line:
200+
201+
```bash
202+
git describe --tags --abbrev=0 --match 'v*' --exclude '*-rc*' HEAD~
203+
```
204+
205+
Note that the above query action doesn't have any way to know if the last tag was a released tag or not.
206+
207+
If you want to generate a changelog against only those tags which have been released via GitHub Releases, you could use `curl` and `jq` to pull from GitHub Releases and take the last version. As an example:
208+
209+
```bash
210+
function latest.tag {
211+
local uri="https://api.github.com/repos/${1}/releases"
212+
local ver=$(curl -s ${uri} | jq -r 'first(.[]|select(.prerelease==false)).tag_name')
213+
echo $ver
214+
}
215+
216+
echo "$(latest.tag ${GITHUB_REPOSITORY})"
217+
```
218+
219+
The `GITHUB_REPOSITORY` variable is available to all GitHub Actions. See GitHub Action documentation on [using environment variables](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables) for more details.
220+
221+
#### Query the **TO** Tag
222+
223+
The latest tag can also be queried using [jimschubert/query-tag-action@v1](https://github.com/jimschubert/query-tag-action):
224+
225+
```yaml
226+
- name: Find Current Tag
227+
id: current
228+
uses: jimschubert/query-tag-action@v1
229+
with:
230+
include: 'v*'
231+
exclude: '*-rc*'
232+
commit-ish: '@'
233+
skip-unshallow: 'true'
234+
```
235+
236+
This action will output the found tag (or fail if no tag is found). It can later be referenced according to the `id` as `${{steps.current.outputs.tag}}`.
237+
238+
If your workflow runs on the [release event](https://help.github.com/en/actions/reference/events-that-trigger-workflows#release-event-release), you may also manipulate the `GITHUB_REF` variable:
239+
240+
```bash
241+
latest=${GITHUB_REF#refs/tags/}
242+
```
243+
244+
Note that the above will always take the tag applied for the current release build and doesn't really allow for filtering as with the above action. If you apply multiple tags to the same commit (e.g. `v1.0.0-rc`, `v1.0.0-prerelease`), the workflow run will result in the tag which triggered that run.
245+
246+
#### Include the Beast Changelog Action
247+
248+
The action may be defined with full options (FROM and TO options assume query-tag-action examples from above):
249+
250+
```yaml
251+
- name: Create Changelog
252+
id: changelog
253+
uses: jimschubert/beast-changelog-action@v1
254+
with:
255+
GITHUB_TOKEN: ${{github.token}}
256+
GITHUB_REPOSITORY: ${{github.repository}}
257+
CONFIG_LOCATION: .github/changelog.json
258+
FROM: ${{steps.last.outputs.tag}}
259+
TO: ${{steps.current.outputs.tag}}
260+
OUTPUT: .github/CHANGELOG.md
261+
```
262+
263+
The `GITHUB_TOKEN`, `GITHUB_REPOSITORY`, and `CONFIG_LOCATION` inputs are optional. When should you change these?
264+
265+
* You should consider creating a secret using a service account whenever using a third-party action, as the `github.token`/`GITHUB_TOKEN` provided by default to actions has full account access. This action requires only `public_repo` access.
266+
* You really only need to modify `GITHUB_REPOSITORY` if you're orchestrating changelogs from a repository which is different from your target repository.
267+
* You should update `CONFIG_LOCATION` if you store your changelog configuration somewhere other than the default (for instance, if you decide to use YAML).
268+
269+
The `FROM` and `TO` options are required and have no defaults.
270+
271+
The `OUTPUT` option may be omitted, but `.github/CHANGELOG.md` may not be a desirable location. This file is created and appended to.
272+
273+
*This action does not support prepending to an existing file.* Please add another step to prepend `.github/CHANGELOG.md` to your target file.
274+
275+
#### Full Workflow Example
276+
277+
The following example workflow could be used to copy/paste changelogs into a Release created in GitHub:
278+
279+
```yaml
280+
name: Dump Changelog
281+
on: [release]
282+
283+
jobs:
284+
285+
changelogger:
286+
runs-on: ubuntu-latest
287+
288+
steps:
289+
- name: Checkout
290+
uses: actions/checkout@v2
291+
- name: Unshallow
292+
run: git fetch --prune --unshallow
293+
- name: Find Last Tag
294+
id: last
295+
uses: jimschubert/query-tag-action@v1
296+
with:
297+
include: 'v*'
298+
exclude: '*-rc*'
299+
commit-ish: 'HEAD~'
300+
skip-unshallow: 'true'
301+
- name: Find Current Tag
302+
id: current
303+
uses: jimschubert/query-tag-action@v1
304+
with:
305+
include: 'v*'
306+
exclude: '*-rc*'
307+
commit-ish: '@'
308+
skip-unshallow: 'true'
309+
- name: Create Changelog
310+
id: changelog
311+
uses: jimschubert/beast-changelog-action@v1
312+
with:
313+
FROM: ${{steps.last.outputs.tag}}
314+
TO: ${{steps.current.outputs.tag}}
315+
- name: View Changelog
316+
run: cat .github/CHANGELOG.md
317+
```
318+
319+
Inspect the output of the `View Changelog` step.
320+
321+
## License
322+
323+
This project is [licensed](./LICENSE) under Apache 2.0.

0 commit comments

Comments
 (0)