From a023e6ac219ac53fb78e2af067a8a8af1b9f6a7b Mon Sep 17 00:00:00 2001 From: Nils Andresen Date: Fri, 11 Sep 2020 23:25:51 +0200 Subject: [PATCH] (GH-612) added a section on non-local build providers (called CI-systems here), specifically pointing out that one provider/os-combination has to be marked "primus inter pares" using preferredBuildProviderType / preferredBuildAgentOperatingSystem. Also started on documenting the different (non-local) build providers. --- docs/input/docs/ci-systems/appveyor.md | 32 ++++++++++++ docs/input/docs/ci-systems/azure.md | 29 +++++++++++ docs/input/docs/ci-systems/github.md | 67 +++++++++++++++++++++++++ docs/input/docs/ci-systems/index.cshtml | 31 ++++++++++++ docs/input/docs/ci-systems/teamcity.md | 7 +++ docs/input/docs/ci-systems/travisci.md | 42 ++++++++++++++++ 6 files changed, 208 insertions(+) create mode 100644 docs/input/docs/ci-systems/appveyor.md create mode 100644 docs/input/docs/ci-systems/azure.md create mode 100644 docs/input/docs/ci-systems/github.md create mode 100644 docs/input/docs/ci-systems/index.cshtml create mode 100644 docs/input/docs/ci-systems/teamcity.md create mode 100644 docs/input/docs/ci-systems/travisci.md diff --git a/docs/input/docs/ci-systems/appveyor.md b/docs/input/docs/ci-systems/appveyor.md new file mode 100644 index 00000000..05ade876 --- /dev/null +++ b/docs/input/docs/ci-systems/appveyor.md @@ -0,0 +1,32 @@ +--- +Order: 10 +Title: AppVeyor +Description: Running on AppVeyor +--- + +## Specifics + +* PR-Builds + + In organisations with large amounts of projects (like cake-contrib) it is advaisable to *not* run + pull-requests on AppVeyor (if using the OSS-plan in AppVeyor), to + reduce the amount of build-time. + This change can not be done in the yaml but must be done manually in the UI. + + Go to AppVeyor project -> settings -> "Do not build on "Pull Request" events" to disable building on pull-requests. + +## Example Config + +```yaml +image: + - Visual Studio 2019 + +test: off +build: off + +build_script: + - ps: .\build.ps1 --target=CI + +cache: + - "tools -> recipe.cake" +``` diff --git a/docs/input/docs/ci-systems/azure.md b/docs/input/docs/ci-systems/azure.md new file mode 100644 index 00000000..ca7b6ef7 --- /dev/null +++ b/docs/input/docs/ci-systems/azure.md @@ -0,0 +1,29 @@ +--- +Order: 20 +Title: Azure Pipelines +Description: Running on Azure Pipelines +--- + +## Specifics + +None. + +## Example Config + +```yaml +pool: + vmImage: 'windows-latest' + +steps: +- task: Cache@2 + inputs: + key: '"$(Agent.OS)" | recipe.cake' + path: 'tools' +- task: Cake@2 + inputs: + script: 'recipe.cake' + target: 'CI' + verbosity: 'Normal' + Bootstrap: true + Version: '0.38.4' +``` diff --git a/docs/input/docs/ci-systems/github.md b/docs/input/docs/ci-systems/github.md new file mode 100644 index 00000000..8fa53895 --- /dev/null +++ b/docs/input/docs/ci-systems/github.md @@ -0,0 +1,67 @@ +--- +Order: 30 +Title: GitHub Actions +Description: Building with GitHub Actions +--- + +## Specifics + +* `Upload-Artifacts`-Task + + Uploading artifacts is currently not supported in Cake.Recipe. Please use the `actions/upload-artifacts` GitHub Action. + +* `actions/checkout` + + The default for `fetch-depth` is `1` - this currently does not work with `GitVersion`. Set `fetch-depth: 0` to fetch all history for all branches. + +## Example Config + +```yaml +name: Build + +on: + push: + +jobs: + build: + runs-on: windows-latest + + steps: + - uses: actions/checkout@v2.2.0 + with: + fetch-depth: 0 + + - name: Cache Tools + uses: actions/cache@v2 + with: + path: tools + key: ${{ runner.os }}-tools-${{ hashFiles('recipe.cake') }} + + - name: Setup .NET Core 3.1 + uses: actions/setup-dotnet@v1.5.0 + with: + dotnet-version: 3.1.107 + + - name: Build project + uses: cake-build/cake-action@v1 + with: + script-path: recipe.cake + target: CI + verbosity: Normal + cake-version: 0.38.4 + cake-bootstrap: true + + - name: Upload Issues-Report + uses: actions/upload-artifact@v2 + with: + if-no-files-found: warn + name: issues + path: BuildArtifacts/report.html + + - name: Upload Packages + uses: actions/upload-artifact@v2 + with: + if-no-files-found: warn + name: package + path: BuildArtifacts/Packages/**/* +``` diff --git a/docs/input/docs/ci-systems/index.cshtml b/docs/input/docs/ci-systems/index.cshtml new file mode 100644 index 00000000..e87cb539 --- /dev/null +++ b/docs/input/docs/ci-systems/index.cshtml @@ -0,0 +1,31 @@ +--- +Order: 35 +Title: CI-systems +Description: Overview about CI-systems and how to use them +--- + +

Using a CI-system

+

+Generally using Cake.Recipe on any ci-system is not different from using it locally. +However, some CI-systems need different preparations than others. +

+ + +

Using multiple CI-systems (or running multiple builds on the same system)

+

+When a single commit is built multiple times +(because of multiple CI-systems and/or multiple builds in the same system) +some tasks (generally all tasks that involve some publishing) should only run once (to avoid publishing more than once). +

+

+To ensure that those tasks are run only once, Cake.Recipe provides two setting: +

+ + + +

CI-systems

+ +@Html.Partial("_ChildPages") diff --git a/docs/input/docs/ci-systems/teamcity.md b/docs/input/docs/ci-systems/teamcity.md new file mode 100644 index 00000000..495a1f35 --- /dev/null +++ b/docs/input/docs/ci-systems/teamcity.md @@ -0,0 +1,7 @@ +--- +Order: 40 +Title: TeamCity +Description: Running on TeamCity +--- + +This documentation is currently missing. \ No newline at end of file diff --git a/docs/input/docs/ci-systems/travisci.md b/docs/input/docs/ci-systems/travisci.md new file mode 100644 index 00000000..0c6e8976 --- /dev/null +++ b/docs/input/docs/ci-systems/travisci.md @@ -0,0 +1,42 @@ +--- +Order: 50 +Title: Travis CI +Description: Running on Travis CI +--- + +## Specifics + +* `Upload-Artifacts`-Task + + Travis CI does not have artifacts storage therefore uploading artifacts is not supported in Cake.Recipe. + +* `actions/checkout` + + The default for `fetch-depth` currently does not work with `GitVersion`. Set `depth: false` under `git:` to fetch all history for all branches. + +## Example Config + +*The example shows a build-configuarion for Travis CI, using windows. +Keep in mind using windows in Travis CI is currently an [early release](https://docs.travis-ci.com/user/reference/windows) +and not everything is fully supported.* + +```yaml +language: csharp +os: windows +mono: none +dotnet: none + +cache: + directories: + - tools + +git: + depth: false + +before_install: + - choco install dotnetcore-sdk -version 3.1.402 + - powershell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine + +script: + - powershell ./build.ps1 +``` \ No newline at end of file