Skip to content

Commit 3bc5bca

Browse files
flaxelflaxel
authored
📝 Improve documentation (#30)
* 📝 improve autodev documentation * 📝 improve jira documentation * 📝 improve gitops documentation * 📝 improve release documentation * 📝 improve sonarcloud documentation * 📝 improve stale documentation * 📝 improve yamllint action * 📝 add minor improvements * 🎨 add review suggestions
1 parent 88c6b61 commit 3bc5bca

File tree

1 file changed

+108
-35
lines changed

1 file changed

+108
-35
lines changed

‎README.md‎

Lines changed: 108 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ on:
1414

1515
jobs:
1616
<action name>:
17-
uses: Staffbase/gha-workflows/.github/workflows/template_*.yml@<version>
17+
uses: Staffbase/gha-workflows/.github/workflows/template_*.yml@v1.3.0
1818
with:
1919
...
2020
```
@@ -39,20 +39,67 @@ on:
3939

4040
jobs:
4141
autodev:
42-
uses: Staffbase/gha-workflows/.github/workflows/template_autodev.yml@<version>
42+
uses: Staffbase/gha-workflows/.github/workflows/[email protected]
43+
with:
44+
# optional: base branch from which the history originates, default: main
45+
base: master
46+
# optional: name of the dev branch, default: dev
47+
branch: your dev branch
48+
# optional: update status comment, default: false
49+
# if you want to change the message, please adapt 'success_comment' and/or 'failure_comment'
50+
comments: true
51+
# optional: update status label, default: false
52+
# if you want to change the labels, please adapt 'success_label' and/or 'failure_label'
53+
labels: true
54+
# optional: label which should trigger the action, default: dev
55+
label: deploy
56+
# optional: name of the user which does the commit, default: AutoDev Action
57+
user: your name
58+
# optional: mail of the user which does the commit, default: [email protected]
59+
email: your mail
4360
secrets:
61+
# token to fetch the pull requests
4462
token: ${{ <your-token> }}
4563
```
64+
</details>
65+
66+
### GitOps
67+
68+
<details>
69+
<summary>The action can be used to build and publish a docker image.</summary>
4670
47-
| Property | Required | Type | Default |
48-
|---|---|---|---|
49-
| base | false | string | `main` |
50-
| branch | false | string | `dev` |
51-
| comments | false | boolean | `false` |
52-
| email | false | string | `[email protected]` |
53-
| label | false | string | `dev` |
54-
| user | false | string | `AutoDev Action` |
71+
```yml
72+
name: GitOps
73+
on: [push]
5574

75+
jobs:
76+
gitops:
77+
uses: Staffbase/gha-workflows/.github/workflows/[email protected]
78+
with:
79+
# optional: list of build-time variables
80+
dockerbuildargs: |
81+
"any important args"
82+
# optional: set the target stage to build
83+
dockerbuildtarget: "any target"
84+
# optional: name of the docker image, default: private/<repository_name>
85+
dockerimage: ${{ inputs.image }}
86+
# optional: files which should be updated for dev
87+
gitopsdev: |-
88+
your files
89+
# optional: files which should be updated for stage
90+
gitopsstage: |-
91+
your files
92+
# optional: files which should be updated for prod
93+
gitopsprod: |-
94+
your files
95+
secrets:
96+
# token to access the repository
97+
gitops_token: ${{ <your-gitops-token> }}
98+
# username for the docker registry
99+
docker_username: ${{ <your-docker-username> }}
100+
# password for the docker registry
101+
docker_password: ${{ <your-docker-password> }}
102+
```
56103
</details>
57104
58105
### Jira Ticket Tagging
@@ -71,40 +118,30 @@ on:
71118

72119
jobs:
73120
jira_annotate:
74-
uses: Staffbase/gha-workflows/.github/workflows/template_jira_tagging.yml@<version>
121+
uses: Staffbase/gha-workflows/.github/workflows/template_jira_tagging.yml@v1.3.0
75122
with:
123+
# name of the service to add as label
76124
name: 'component name'
125+
# optional: regex to match the tags
126+
tag_matcher: your regex
77127
secrets:
128+
# basic url for jira api
78129
jira_url: ${{ <your-url> }}
130+
# api token for jira usage
79131
jira_token: ${{ <your-token> }}
132+
# email of the api token owner
80133
jira_email: ${{ <your-email> }}
81134
```
82135
</details>
83136
84-
### GitOps
85-
86-
<details>
87-
<summary>The action can be used to build and publish a docker image.</summary>
88-
89-
```yml
90-
name: GitOps
91-
on: [push]
92-
93-
jobs:
94-
gitops:
95-
uses: Staffbase/gha-workflows/.github/workflows/template_gitops.yml@<version>
96-
secrets:
97-
gitops_token: ${{ <your-gitops-token> }}
98-
docker_username: ${{ <your-docker-username> }}
99-
docker_password: ${{ <your-docker-password> }}
100-
```
101-
</details>
102-
103137
### Release Drafter
104138
105139
<details>
106140
<summary>The action can be used to draft automatically a new release.</summary>
107141
142+
If you want to use the template action please note that you must have the configuration file `.github/release-drafter.yml`.
143+
More information on how to configure this file can be found [here](https://github.com/marketplace/actions/release-drafter#configuration).
144+
108145
```yml
109146
name: Release Drafter
110147
@@ -115,7 +152,16 @@ on:
115152
116153
jobs:
117154
update_release_draft:
118-
uses: Staffbase/gha-workflows/.github/workflows/template_release_drafter.yml@<version>
155+
uses: Staffbase/gha-workflows/.github/workflows/[email protected]
156+
with:
157+
# optional: name of the release
158+
name: Version X.Y.Z
159+
# optional: should the release be published, default: false
160+
publish: true
161+
# optional: tag name of the release
162+
tag: vX.Y.Z
163+
# optional: version to be associated with the release
164+
version: X.Y.Z
119165
```
120166
</details>
121167

@@ -124,6 +170,9 @@ jobs:
124170
<details>
125171
<summary>The action can be used to analyze a project with sonarcloud.</summary>
126172

173+
If you want to use this action you need to add the project metadata in the file `sonar-project.properties` in the base directory.
174+
More information on how to set this up can be found [here](https://github.com/SonarSource/sonarcloud-github-action#usage).
175+
127176
```yml
128177
name: Sonarcloud
129178
@@ -136,19 +185,25 @@ on:
136185
137186
jobs:
138187
sonarcloud:
139-
uses: Staffbase/gha-workflows/.github/workflows/template_sonarcloud.yml@<version>
188+
uses: Staffbase/gha-workflows/.github/workflows/template_sonarcloud.yml@v1.3.0
140189
with:
190+
# path to the cached coverage file
141191
path: <path-to-cached-coverage-file>
192+
# optional: additional arguments for action
193+
args: >
194+
your commands
142195
secrets:
196+
# token to access pull request
143197
token: ${{ secrets.GITHUB_TOKEN }}
198+
# token to access sonarcloud
144199
sonar_token: ${{ <your_token> }}
145200
```
146201

147202
It is necessary that the coverage file is cached with the following code:
148203

149204
```yml
150205
- name: Cache Coverage Data
151-
uses: actions/cache@<version>
206+
uses: actions/cache@v3.0.2
152207
with:
153208
path: <path-to-cached-coverage-file>
154209
key: ${{ runner.os }}-coverage-data
@@ -170,7 +225,20 @@ on:
170225
171226
jobs:
172227
stale:
173-
uses: Staffbase/gha-workflows/.github/workflows/template_stale.yml@<version>
228+
uses: Staffbase/gha-workflows/.github/workflows/[email protected]
229+
with:
230+
# optional: comment on the stale pull request while closed, default: This stale PR was closed because there was no activity.
231+
close-pr-message: your message
232+
# optional: idle number of days before marking pull requests stale, default: 60
233+
days-before-stale: 30
234+
# optional: delete branch after closing the pull request, default: true
235+
delete-branch: false
236+
# optional: labels on pull requests exempted from stale
237+
exempt-pr-labels: your labels
238+
# optional: label to apply on staled pull requests, default: stale
239+
stale-pr-label: staling
240+
# optional: comment on the staled pull request, default: This PR has been automatically marked as stale because there has been no recent activity in the last 60 days. It will be closed in 7 days if no further activity occurs such as removing the label.
241+
stale-pr-message: your message
174242
```
175243
</details>
176244

@@ -191,7 +259,12 @@ on:
191259
192260
jobs:
193261
yamllint:
194-
uses: Staffbase/gha-workflows/.github/workflows/template_yaml.yml@<version>
262+
uses: Staffbase/gha-workflows/.github/workflows/[email protected]
263+
with:
264+
# optional: name of the running action, default: yamllint / yamllint
265+
action-name: your name
266+
# optional: path which files should be checked recursively, default: .
267+
target-path: your path
195268
```
196269
</details>
197270

0 commit comments

Comments
 (0)