Skip to content

Commit 26417b1

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

File tree

1 file changed

+291
-0
lines changed

1 file changed

+291
-0
lines changed

‎CI.md‎

Lines changed: 291 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,289 @@ 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+
# Do not use the normal GITHUB_TOKEN here.
377+
# It will prevent builds running on tags to be initiated.
378+
GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
379+
runs-on: ubuntu-latest
380+
381+
steps:
382+
- uses: actions/checkout@v2
383+
with:
384+
ref: ${{ github.event.ref }}
385+
- name: Fetch all tags and branches
386+
run: git fetch --prune --unshallow
387+
- name: Cache Tools
388+
uses: actions/cache@v2
389+
with:
390+
path: tools
391+
key: ${{ runner.os }}-draft-tools-${{ hashFiles('build.cake') }}
392+
- name: Set up git version
393+
if: ${{ !contains(github.ref, '/hotfix/') && !contains(github.ref, '/release/') }}
394+
uses: gittools/actions/gitversion/[email protected]
395+
with:
396+
versionSpec: "5.x"
397+
- name: Run git version
398+
if: ${{ !contains(github.ref, '/hotfix/') && !contains(github.ref, '/release/') }}
399+
id: gitversion
400+
uses: gittools/actions/gitversion/[email protected]
401+
- name: Create release branch ${{ github.event.inputs.version }}
402+
if: ${{ steps.gitversion.outputs.majorMinorPatch }}
403+
run: git switch -c release/${{ steps.gitversion.outputs.majorMinorPatch }}
404+
- name: Push new branch
405+
if: ${{ steps.gitversion.outputs.majorMinorPatch }}
406+
uses: ad-m/[email protected]
407+
with:
408+
branch: "release/${{ steps.gitversion.outputs.majorMinorPatch }}"
409+
github_token: ${{ secrets.GH_TOKEN }}
410+
- name: Drafting Release Notes
411+
uses: cake-build/cake-action@v1
412+
with:
413+
script-path: recipe.cake
414+
target: releasenotes
415+
cake-version: 0.38.4
416+
cake-bootstrap: true
417+
```
418+
419+
##### Drafting new pre-release
420+
421+
```yml
422+
name: Draft Pre Release Notes
423+
424+
on:
425+
workflow_dispatch:
426+
427+
jobs:
428+
draft-pre-release:
429+
env:
430+
# Do not use the normal GITHUB_TOKEN here.
431+
# It will prevent builds running on tags to be initiated.
432+
GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
433+
runs-on: ubuntu-latest
434+
435+
steps:
436+
- uses: actions/checkout@v2
437+
with:
438+
ref: ${{ github.event.ref }}
439+
- name: Fetch all tags and branches
440+
run: git fetch --prune --unshallow
441+
- name: Cache Tools
442+
uses: actions/cache@v2
443+
with:
444+
path: tools
445+
key: ${{ runner.os }}-draft-tools-${{ hashFiles('build.cake') }}
446+
- name: Set up git version
447+
if: ${{ !contains(github.ref, '/hotfix/') && !contains(github.ref, '/release/') }}
448+
uses: gittools/actions/gitversion/[email protected]
449+
with:
450+
versionSpec: "5.x"
451+
- name: Run git version
452+
if: ${{ !contains(github.ref, '/hotfix/') && !contains(github.ref, '/release/') }}
453+
id: gitversion
454+
uses: gittools/actions/gitversion/[email protected]
455+
- name: Create release branch ${{ github.event.inputs.version }}
456+
if: ${{ steps.gitversion.outputs.majorMinorPatch }}
457+
run: git switch -c release/${{ steps.gitversion.outputs.majorMinorPatch }}
458+
- name: Push new branch
459+
if: ${{ steps.gitversion.outputs.majorMinorPatch }}
460+
uses: ad-m/[email protected]
461+
with:
462+
branch: "release/${{ steps.gitversion.outputs.majorMinorPatch }}"
463+
github_token: ${{ secrets.GITHUB_TOKEN }}
464+
- name: Create release notes
465+
# Cake action do not support passing additional arguments.
466+
# As such we need to run the bootstrapper manually
467+
run: ./build.sh --target=releasenotes --create-pre-release
468+
```
469+
179470
<!-- The following migrate docs need to be
180471
updated when migration documentation are
181472
complete -->

0 commit comments

Comments
 (0)