Skip to content

Commit df5da1a

Browse files
eksrhaeksrha
committed
add awesome-ci to docs
1 parent 0d151ae commit df5da1a

File tree

12 files changed

+848
-0
lines changed

12 files changed

+848
-0
lines changed

‎docs/repos/awesome-ci/commands/index.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Commands
2+
3+
Overview of all available transfer parameters.
4+
5+
These commands are used to get information in a pipeline or local build.
6+
7+
Some calls can also create releases or more.
8+
9+
## Command structure
10+
11+
```bash
12+
awesome-ci <subcommand> [subcommand-option]
13+
```
14+
15+
| Option | Description | requiered |
16+
| ---------- | -------------------------------------------- | :-------: |
17+
| `-version` | Returns current used version form awesome-ci | false |
18+
19+
### Subcommands
20+
21+
You can find out more about the subcommands by clicking on the relevant one in the navigation.
22+
23+
| Subcommand | Description |
24+
| --------------------------------------- | ------------------------------------------------- |
25+
| [release](/commands/createRelease.html) | creates a release at GitHub or |
26+
| [pr](/commands/getBuildInfos.html) | prints out any git information and can manipulate |
27+
| [parseJSON](/commands/parseJSON.html) | can parse simple JSON |
28+
| [parseYAML](/commands/parseYAML.html) | can parse simple YAML files |
29+
30+
## Release Body updates
31+
32+
Now available: Any string or any markdown file can now be attached in the release section. In addition, the release assets are attached as text to each release body with the associated sha256. More about that in the picture below and in the release section.
33+
34+
![Release Body with Asstes](../pictures/release-assets-readme.png "Release Body with Asstes")

‎docs/repos/awesome-ci/commands/parseJSON.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
layout: default
3+
title: parseJSON
4+
parent: Commands
5+
nav_order: 3
6+
---
7+
8+
# Parsing a JSON File
9+
10+
```bash
11+
awesome-ci parseJSON [subcommand-option]
12+
```
13+
14+
| Subcommand option | Description |
15+
| ----------------- | ------------------------------ |
16+
| `-file` | your file location |
17+
| `-value` | your value you want to extract |
18+
19+
## Examlpe
20+
21+
Example demo.json:
22+
23+
```json
24+
{
25+
"value1": "hello",
26+
"value2": "world",
27+
"deepObject": {
28+
"value1": "hello",
29+
"value2": "world"
30+
}
31+
}
32+
```
33+
34+
Example command 1:
35+
36+
```shell
37+
awesome-ci parseJSON -file demo.json -value .value2
38+
world
39+
```
40+
41+
Example command 2:
42+
43+
```shell
44+
awesome-ci parseJSON -file demo.json -value .deepObject
45+
map[value1:hello value2:world]
46+
```
47+
48+
You can check more details of the json construct in one of the following versions.

‎docs/repos/awesome-ci/commands/parseYAML.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
layout: default
3+
title: parseYAML
4+
parent: Commands
5+
nav_order: 4
6+
---
7+
8+
# Parsing a Yaml File
9+
10+
```bash
11+
awesome-ci parseYAML [subcommand-option]
12+
```
13+
14+
| Subcommand option | Description |
15+
| ----------------- | ------------------------------ |
16+
| `-file` | your file location |
17+
| `-value` | your value you want to extract |
18+
19+
## Examlpe
20+
21+
Example demo.yaml:
22+
23+
```yaml
24+
value1: hello
25+
value2: world
26+
deepObject:
27+
value1: hello
28+
value2: world
29+
```
30+
31+
Example command 1:
32+
33+
```shell
34+
awesome-ci parseYAML -file demo.yaml -value .value2
35+
world
36+
```
37+
38+
Example command 2:
39+
40+
```shell
41+
awesome-ci parseYAML -file demo.yaml -value .deepObject
42+
map[value1:hello value2:world]
43+
```
44+
45+
You can check more details of the yaml construct in one of the following versions.

‎docs/repos/awesome-ci/commands/pr.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# pr
2+
3+
## Overview
4+
5+
```bash
6+
awesome-ci pr <subcommand> [subcommand-option]
7+
```
8+
9+
## Subcommands
10+
11+
| Subcommand | Description |
12+
| ---------- | ------------------------------------------ |
13+
| `info` | creates an release, but doesn't publish it |
14+
15+
| Subcommand option | Description |
16+
| ----------------- | ----------------------------------------------------------------------------- |
17+
| `-number` | overwrite the issue number |
18+
| `-format` | pastes the required output to the console. This can be extracted to variables |
19+
20+
### -number
21+
22+
By default, awesome-ci recognizes the number of the PullRequest being built. To speed up this process and make it more stable, the `-number` can optionally be specified if known. This brings additional stability to the workflow.
23+
24+
### -format
25+
26+
The `-format` option can put out your needed information about your current git status.
27+
28+
Hint: use a seperatoa as you like, the below values would be replaced!
29+
30+
Possible infos are: `patchLevel`, `pr`, `version`, `latest_version`
31+
32+
#### Examples
33+
34+
```bash
35+
#### Info output:
36+
Pull Request: 17
37+
Current release version: 1.0.0
38+
Patch level: feature
39+
Possible new release version: 1.1.0
40+
```
41+
42+
```bash
43+
awesome-ci getBuildInfos -format "pr,next_version"
44+
# Output:
45+
17,1.1.0
46+
```
47+
48+
### Special to github actions
49+
50+
With a github action, all available information is always set as environment variables. Once set the Variables ale awailable in all steps and runners.
51+
52+
```bash
53+
#### Setting Env variables:
54+
ACI_PR=17
55+
ACI_ORGA=eksrvb
56+
ACI_REPO=playground
57+
ACI_BRANCH=bugfix/test-pr
58+
ACI_PATCH_LEVEL=bugfix
59+
ACI_VERSION=0.4.4
60+
ACI_NEXT_VERSION=0.4.5
61+
62+
#### Info output:
63+
Pull Request: 17
64+
Current release version: 0.4.4
65+
Patch level: bugfix
66+
Possible new release version: 0.4.5
67+
```

‎docs/repos/awesome-ci/commands/release.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# release
2+
3+
## Overview
4+
5+
```bash
6+
awesome-ci release <subcommand> [subcommand-option]
7+
```
8+
9+
### Subcommands
10+
11+
| Subcommand | Description |
12+
| ---------- | -------------------------------------------------------------------------- |
13+
| `create` | creates an release, but doesn't publish it |
14+
| `publish` | publishes an existing release with an given release id or makes an new one |
15+
16+
| Subcommand option | Description |
17+
| ----------------- | ------------------------------------------------------------------------------------------------ |
18+
| `-version` | overrides any version from git and, or patches the given string |
19+
| `-patchLevel` | overrides the patchLevel. make shure your following the alias definition. |
20+
| `-dry-run` | doesn't create a release. Prints out what it would do and check permissions |
21+
| `-body` | add a text (markdown) to the release body eg.: `./release-template-md` |
22+
| `-merge-sha` | specify the merge sha |
23+
| `-release-branch` | set release branch (default: git default) |
24+
| `-assets` | (only available in publish) uploads the given Artifacts to a release. Eg.: `file=out/awesome-ci` |
25+
| `-releaseid` | (only available in publish) publishes an early defined release |
26+
27+
#### -version and -patchLevel
28+
29+
The `-version` option can overwrite the evaluated version.
30+
This can be useful in connection with `-patchLevel` when creating a manual release.
31+
32+
```bash
33+
awesome-ci createRelease -version 0.1.0
34+
```
35+
36+
#### -assets
37+
38+
The `-assets` option can updload a single or multiple artifacts.
39+
40+
However, you must choose the format of the artefacts.
41+
42+
eg.: `-assets "file=path/to/file,file=path/to/second/file"`
43+
44+
#### -body
45+
46+
Send a custom release description. the input can be either a string or a path to a file.
47+
48+
![Release Body with Asstes](../pictures/release-assets-readme.png "Release Body with Asstes")
49+
50+
... more documentation to be done ;)

‎docs/repos/awesome-ci/examples/github_actions.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
### Build a Release
2+
3+
This is an example from th awesome-ci project you can find the original workflow [here](https://github.com/fullstack-devops/awesome-ci/blob/main/.github/workflows/Release.yaml)
4+
5+
```yaml
6+
name: Publish Release
7+
8+
on:
9+
push:
10+
branches:
11+
- "main"
12+
paths-ignore:
13+
- "README.md"
14+
- 'docs/**'
15+
- '.github/ISSUE_TEMPLATE/**'
16+
- '.github/PULL_REQUEST_TEMPLATE.md'
17+
18+
19+
jobs:
20+
generate_infos:
21+
runs-on: ubuntu-latest
22+
outputs:
23+
releaseid: $\{\{ steps.tag.outputs.releaseid \}\}
24+
version: $\{\{ steps.tag.outputs.version \}\}
25+
pr: $\{\{ steps.tag.outputs.pr \}\}
26+
steps:
27+
- name: Check out the repo
28+
uses: actions/checkout@v2
29+
- name: Setup awesome-ci
30+
uses: fullstack-devops/awesome-ci-action@main
31+
32+
- name: collect infos and create release
33+
run: |
34+
awesome-ci pr info
35+
awesome-ci release create -merge-sha $\{\{ github.sha \}\}
36+
env:
37+
GITHUB_TOKEN: $\{\{ secrets.GITHUB_TOKEN \}\}
38+
39+
- name: collect infos
40+
id: tag
41+
shell: bash
42+
run: |
43+
echo "::set-output name=version::$ACI_VERSION"
44+
echo "::set-output name=pr::$ACI_PR"
45+
echo "::set-output name=releaseid::$ACI_RELEASE_ID"
46+
47+
build:
48+
runs-on: ubuntu-latest
49+
needs: generate_infos
50+
strategy:
51+
matrix:
52+
arch: ["amd64", "arm64"]
53+
steps:
54+
- name: Checkout code
55+
uses: actions/checkout@v2
56+
- name: Set up Go
57+
uses: actions/setup-go@v2
58+
with:
59+
go-version: 1.17
60+
61+
- name: Build "$\{\{ matrix.arch \}\}"
62+
run: go build -v -ldflags "-X main.version=$\{\{ needs.generate_infos.outputs.version \}\}" -o out/awesome-ci_$\{\{ needs.generate_infos.outputs.version \}\}_$\{\{ matrix.arch \}\}
63+
env:
64+
GOOS: linux
65+
GOARCH: "$\{\{ matrix.arch \}\}"
66+
67+
- name: Cache build outputs
68+
uses: actions/cache@v2
69+
env:
70+
cache-name: cache-outputs-modules
71+
with:
72+
path: out/
73+
key: awesome-ci-$\{\{ github.sha \}\}-$\{\{ hashFiles('out/awesome-ci*') \}\}
74+
restore-keys: |
75+
awesome-ci-$\{\{ github.sha \}\}
76+
77+
publish_release:
78+
runs-on: ubuntu-latest
79+
needs: [generate_infos, build]
80+
steps:
81+
- name: Checkout code
82+
uses: actions/checkout@v2
83+
- name: Setup awesome-ci
84+
uses: fullstack-devops/awesome-ci-action@main
85+
86+
- name: get cached build outputs
87+
uses: actions/cache@v2
88+
env:
89+
cache-name: cache-outputs-modules
90+
with:
91+
path: out/
92+
key: awesome-ci-$\{\{ github.sha \}\}
93+
94+
- name: Publish Release
95+
run: awesome-ci release publish -releaseid "$ACI_RELEASE_ID" -assets "file=out/$ARTIFACT1,file=out/$ARTIFACT2"
96+
env:
97+
GITHUB_TOKEN: $\{\{ secrets.GITHUB_TOKEN \}\}
98+
ACI_RELEASE_ID: $\{\{ needs.generate_infos.outputs.releaseid \}\}
99+
ARTIFACT1: awesome-ci_$\{\{ needs.generate_infos.outputs.version \}\}_amd64
100+
ARTIFACT2: awesome-ci_$\{\{ needs.generate_infos.outputs.version \}\}_arm64
101+
```
102+
103+
You need more examples? Please open an issue!

‎docs/repos/awesome-ci/examples/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Examples
2+
3+
All available examples are shown here.
4+
If you need support with a pipeline not shown here, you are welcome to open an issue.
5+
6+
The examples for Jenkins and Gitlab Ci are coming soon!

‎docs/repos/awesome-ci/images/aci-workflow.drawio.png‎

66.1 KB
Loading

‎docs/repos/awesome-ci/images/release-assets-readme.png‎

47.4 KB
Loading

0 commit comments

Comments
 (0)