Skip to content

Commit 32adfed

Browse files
AdmiringWormAdmiringWorm
committed
(docs) Add documentation regarding setting up github actions builds
1 parent e97f6b1 commit 32adfed

File tree

1 file changed

+287
-0
lines changed

1 file changed

+287
-0
lines changed

‎CI.md

Lines changed: 287 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,14 @@
1010
- [Using Cake.Recipe 1.x with AppVeyor](#using-cakerecipe-1x-with-appveyor)
1111
- [Additional notes](#additional-notes)
1212
- [Using Azure Pipelines](#using-azure-pipelines)
13+
- [Using GitHub Actions](#using-github-actions)
14+
- [Available Organization Secrets](#available-organization-secrets)
15+
- [Using Cake.Recipe 2.x with GitHub Actions](#using-cakerecipe-2x-with-github-actions)
16+
- [Additional workflows](#additional-workflows)
17+
- [Forcing documentation publishing](#forcing-documentation-publishing)
18+
- [Drafting new releases](#drafting-new-releases)
19+
- [Drafting new stable release](#drafting-new-stable-release)
20+
- [Drafting new pre-release](#drafting-new-pre-release)
1321

1422
<!-- /TOC -->
1523
<!-- markdownlint-enable -->
@@ -176,6 +184,285 @@ pre-release instead.
176184
There is currently no documentation on how to set up Cake Contrib addins for
177185
building on Azure Pipelines.
178186

187+
## Using GitHub Actions
188+
189+
### Available Organization Secrets
190+
191+
The following secrets are provided on the organization level and can be made
192+
available in GitHub workflows.
193+
See the examples of how these can be made available for usage.
194+
Unless configured per repository, these secrets are not available when running
195+
workflows toward pull requests (_we do not recommend changing settings to allow this_).
196+
Maintainers may also go to `Settings --> Secrets` to see the available secrets
197+
set (you will not be able to see the values).
198+
199+
- `APPVEYOR_API_TOKEN` (_Should not be needed on GitHub Actions in general_)
200+
- `AZURE_PASSWORD`
201+
- `AZURE_SOURCE`
202+
- `AZURE_USER`
203+
- `GH_TOKEN` (In most cases, this token should be used instead of `GITHUB_TOKEN`
204+
as using the latter will prevent any workflows from triggering.)
205+
- `GITTER_ROOM_ID`
206+
- `GITTER_TOKEN`
207+
- `GPR_PASSWORD`
208+
- `GPR_SOURCE`
209+
- `GPR_USER`
210+
- `MYGET_API_KEY`
211+
- `MYGET_SOURCE`
212+
- `NUGET_API_KEY`
213+
- `NUGET_SOURCE`
214+
- `TWITTER_ACCESS_TOKEN`
215+
- `TWITTER_ACCESS_TOKEN_SECRET`
216+
- `TWITTER_CONSUMER_KEY`
217+
- `TWITTER_CONSUMER_SECRET`
218+
- `WYAM_ACCESS_TOKEN`
219+
(_`GITHUB_TOKEN` can also be used, but we recommend to use this token instead_)
220+
- `WYAM_DEPLOY_BRANCH` (_provided for convenience_)
221+
222+
### Using Cake.Recipe 2.x with GitHub Actions
223+
224+
For using GitHub Actions as the preferred build provider, it is necessary to use
225+
Cake.Recipe 2.x.
226+
Using Cake 1.x will require overriding criteria on publishing tasks,
227+
and it completely unsupported.
228+
229+
You can use the following minimal workflow file if you want to use Cake.Recipe
230+
together with GitHub Actions.
231+
232+
```yml
233+
name: Build
234+
235+
on:
236+
push:
237+
branch:
238+
- master
239+
- develop
240+
- "release/**"
241+
- "hotfix/**"
242+
# Add any additional branches you wish to run the workflow on
243+
pull_request:
244+
245+
jobs:
246+
build:
247+
runs-on: ${{ matrix.os }}
248+
strategy:
249+
os: [windows-latest, ubuntu-latest, macos-latest]
250+
env:
251+
AZURE_PASSWORD: ${{ secrets.AZURE_PASSWORD }}
252+
AZURE_SOURCE: ${{ secrets.AZURE_SOURCE }}
253+
AZURE_USER: ${{ secrets.AZURE_USER }}
254+
GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
255+
GITTER_ROOM_ID: ${{ secrets.GITTER_ROOM_ID }}
256+
GITTER_TOKEN: ${{ secrets.GITTER_TOKEN }}
257+
GPR_PASSWORD: ${{ secrets.GPR_PASSWORD }}
258+
GPR_SOURCE: ${{ secrets.GPR_SOURCE }}
259+
GPR_USER: ${{ secrets.GPR_USER }}
260+
# The MyGet related environment variables are currently not recommended
261+
# to be used. But kept here for completeness.
262+
MYGET_API_KEY: ${{ secrets.MYGET_API_KEY }}
263+
MYGET_SOURCE: ${{ secrets.MYGET_SOURCE }}
264+
NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}
265+
NUGET_SOURCE: ${{ secrets.NUGET_SOURCE }}
266+
TWITTER_ACCESS_TOKEN: ${{ secrets.TWITTER_ACCESS_TOKEN }}
267+
TWITTER_ACCESS_TOKEN_SECRET: ${{ secrets.TWITTER_ACCESS_TOKEN_SECRET }}
268+
TWITTER_CONSUMER_KEY: ${{ secrets.TWITTER_CONSUMER_KEY }}
269+
TWITTER_CONSUMER_SECRET: ${{ secrets.TWITTER_CONSUMER_SECRET }}
270+
WYAM_ACCESS_TOKEN: ${{ secrets.WYAM_ACCESS_TOKEN }}
271+
WYAM_DEPLOY_BRANCH: "gh-pages"
272+
WYAM_DEPLOY_REMOTE: ${{ github.event.repository.html_url }}
273+
274+
steps:
275+
- uses: actions/checkout@v2
276+
- name: Fetch all tags and branches
277+
run: git fetch --prune --unshallow
278+
- name: Cache Tools
279+
uses: actions/cache@v2
280+
with:
281+
path: tools
282+
# Make any necessary changes to this key if you use a different
283+
# cake build script name.
284+
key: ${{ runner.os }}-tools-${{ hashFiles('recipe.cake') }}
285+
# If you are running unit tests against only .NET Core 3.1,
286+
# then you do not need this step
287+
- name: Set up .NET Core 2.1
288+
uses: actions/[email protected]
289+
with:
290+
dotnet-version: 2.1.809
291+
- name: Build Addin
292+
uses: cake-build/cake-action@v1
293+
with:
294+
# Change the script path to your actual cake script file
295+
script-path: recipe.cake
296+
target: CI
297+
cake-version: 0.38.4
298+
cake-bootstrap: true
299+
# The followingi is untested, and need verification
300+
- name: Upload artifacts
301+
uses: actions/upload-artifacts@v2
302+
with:
303+
name: ${{ runner.os }}-artifacts
304+
path: |
305+
BuildArtifacts/issues-report.html
306+
Buildartifacts/packages/**/*.nupkg
307+
BuildArtifacts/**/coverlet/*.xml
308+
```
309+
310+
### Additional workflows
311+
312+
The following workflow files are made available to make particular release
313+
related tasks more comfortable to achieve.
314+
Use of these files should be in addition to the standard build workflow file.
315+
316+
#### Forcing documentation publishing
317+
318+
When there is a need to force publishing a new set of documentation, then the
319+
following workflow may be used to allow this.
320+
The workflow will run from the branch that is configured as the base branch when
321+
triggering the run.
322+
323+
```yml
324+
name: Publish Documentation
325+
326+
on:
327+
workflow_dispatch:
328+
329+
jobs:
330+
publish-docs:
331+
env:
332+
WYAM_ACCESS_TOKEN: ${{ secrets.WYAM_ACCESS_TOKEN }}
333+
WYAM_DEPLOY_REMOTE: "${{ github.event.repository.html_url }}"
334+
WYAM_DEPLOY_BRANCH: "gh-pages"
335+
# ubuntu-latest is used here due to it is
336+
# the one taking the shortest time to execute
337+
runs-on: ubuntu-latest
338+
339+
steps:
340+
- uses: actions/checkout@v2
341+
with:
342+
ref: ${{ github.event.ref }}
343+
- name: Cache Tools
344+
uses: actions/cache@v2
345+
with:
346+
path: tools
347+
key: ${{ runner.os }}-doc-tools-${{ hashFiles('recipe.cake') }}
348+
- name: Publishing documentaiton
349+
uses: cake-build/cake-action@v1
350+
with:
351+
script-path: recipe.cake
352+
target: Force-Publish-Documentation
353+
cake-version: 0.38.4
354+
cake-bootstrap: true
355+
```
356+
357+
#### Drafting new releases
358+
359+
When it comes the time to release a new stable release of the addin, then you
360+
may use the following workflow file instead of needing to run the necessary
361+
steps locally.
362+
These workflows will create a new branch (when one do not exist) called `release/asserted-version`.
363+
(where asserted-version is the version as detected by GitVersion)
364+
365+
##### Drafting new stable release
366+
367+
```yml
368+
name: Draft Release Notes
369+
370+
on:
371+
workflow_dispatch:
372+
373+
jobs:
374+
draft:
375+
env:
376+
GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
377+
runs-on: ubuntu-latest
378+
379+
steps:
380+
- uses: actions/checkout@v2
381+
with:
382+
ref: ${{ github.event.ref }}
383+
- name: Fetch all tags and branches
384+
run: git fetch --prune --unshallow
385+
- name: Cache Tools
386+
uses: actions/cache@v2
387+
with:
388+
path: tools
389+
key: ${{ runner.os }}-draft-tools-${{ hashFiles('build.cake') }}
390+
- name: Set up git version
391+
if: ${{ !contains(github.ref, '/hotfix/') && !contains(github.ref, '/release/') }}
392+
uses: gittools/actions/gitversion/[email protected]
393+
with:
394+
versionSpec: "5.x"
395+
- name: Run git version
396+
if: ${{ !contains(github.ref, '/hotfix/') && !contains(github.ref, '/release/') }}
397+
id: gitversion
398+
uses: gittools/actions/gitversion/[email protected]
399+
- name: Create release branch ${{ github.event.inputs.version }}
400+
if: ${{ steps.gitversion.outputs.majorMinorPatch }}
401+
run: git switch -c release/${{ steps.gitversion.outputs.majorMinorPatch }}
402+
- name: Push new branch
403+
if: ${{ steps.gitversion.outputs.majorMinorPatch }}
404+
uses: ad-m/[email protected]
405+
with:
406+
branch: "release/${{ steps.gitversion.outputs.majorMinorPatch }}"
407+
github_token: ${{ secrets.GH_TOKEN }}
408+
- name: Drafting Release Notes
409+
uses: cake-build/cake-action@v1
410+
with:
411+
script-path: recipe.cake
412+
target: releasenotes
413+
cake-version: 0.38.4
414+
cake-bootstrap: true
415+
```
416+
417+
##### Drafting new pre-release
418+
419+
```yml
420+
name: Draft Pre Release Notes
421+
422+
on:
423+
workflow_dispatch:
424+
425+
jobs:
426+
draft-pre-release:
427+
env:
428+
GITHUB_TOKEN: ${{ secrets.DRAFT_TOKEN }}
429+
runs-on: ubuntu-latest
430+
431+
steps:
432+
- uses: actions/checkout@v2
433+
with:
434+
ref: ${{ github.event.ref }}
435+
- name: Fetch all tags and branches
436+
run: git fetch --prune --unshallow
437+
- name: Cache Tools
438+
uses: actions/cache@v2
439+
with:
440+
path: tools
441+
key: ${{ runner.os }}-draft-tools-${{ hashFiles('build.cake') }}
442+
- name: Set up git version
443+
if: ${{ !contains(github.ref, '/hotfix/') && !contains(github.ref, '/release/') }}
444+
uses: gittools/actions/gitversion/[email protected]
445+
with:
446+
versionSpec: "5.x"
447+
- name: Run git version
448+
if: ${{ !contains(github.ref, '/hotfix/') && !contains(github.ref, '/release/') }}
449+
id: gitversion
450+
uses: gittools/actions/gitversion/[email protected]
451+
- name: Create release branch ${{ github.event.inputs.version }}
452+
if: ${{ steps.gitversion.outputs.majorMinorPatch }}
453+
run: git switch -c release/${{ steps.gitversion.outputs.majorMinorPatch }}
454+
- name: Push new branch
455+
if: ${{ steps.gitversion.outputs.majorMinorPatch }}
456+
uses: ad-m/[email protected]
457+
with:
458+
branch: "release/${{ steps.gitversion.outputs.majorMinorPatch }}"
459+
github_token: ${{ secrets.GITHUB_TOKEN }}
460+
- name: Create release notes
461+
# Cake action do not support passing additional arguments.
462+
# As such we need to run the bootstrapper manually
463+
run: ./build.sh --target=releasenotes --create-pre-release
464+
```
465+
179466
<!-- The following migrate docs need to be
180467
updated when migration documentation are
181468
complete -->

0 commit comments

Comments
 (0)