DroneHelper/README.md

DroneHelper

🛠️ Helper module for Drone.io based build pipelines.

🔑 General

The DroneHelper PowerShell module adds several features for Gitea -> Drone.IO based build pipelines. It's designed to perform all needed tasks for PowerShell Module development like:

Testing

• Invoke-FileLinter -> Runs basic FileLinter tests with console and log file output
• Invoke-Linter -> Runs PSScriptAnalyzer with embedded to custom profiles.
• Invoke-UnitTest -> Runs Pester tests including code coverage report with console and log file output.

Build Pipeline

• Send-PRComment -> Takes all generated reports and reports them back as Pull Request Comment for a simplified overview.
• Write-FailureStateFile, Invoke-Build -> Marks the current pipeline run / build as failed if the previous steps also raised errors.

Helper

• New-Docs, Update-Docs -> Automatically updates the markdown based docs generated form your Comment Based Help blocks in your functions

Building & Publishing

• Update-ModuleMeta -> Updates the ModuleVersion + Prerelease properties wit the current git tag.
• Merge-ModuleRoot -> Takes all single file functions and merges them into a single *.psm1 file.
• New-BuildPackage -> Creates a new build artifact for an alternate publishing target like a Gitea release.

To use these features, all you have to do, is follow the .drone.yml template:

.drone.yml Template

---
kind: pipeline
type: docker
name: "Build Pipeline"

trigger:
  branch:
    exclude:
      - droneDocs/*

steps:
  - name: "Pwsh FileLinter"
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    failure: ignore
    environment:
      EXCLUDE: "(.exe|.dll|.ico|.gitkeep)"
    commands:
      - |
        apt-get update
        apt-get install -y file        

      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module 'DroneHelper' -ErrorAction 'Stop';
          Invoke-FileLinter
        }"        

  - name: "ScriptAnalyzer"
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    failure: ignore
    commands:
      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Install-ModuleDependency;
          Invoke-Linter
        }"        

  - name: "Pester"
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    failure: ignore
    commands:
      - |
        apt-get update
        apt-get install -y file        

      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Install-ModuleDependency;
          Invoke-UnitTest -Verbosity 'Detailed' -ExcludeTag 'Integration'
        }"        

  - name: "PRComment"
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    failure: ignore
    environment:
      GITEA_TOKEN:
        from_secret: GITEA_TOKEN
      CUSTOM_PIPELINE_STATE: true
      LOG_FILES: "build/*.log"
    commands:
      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Send-PRComment
        }"        
    when:
      event:
        include:
          - pull_request

  - name: "buildState"
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    commands:
      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Install-ModuleDependency;
          Invoke-BuildState
        }"        

---
kind: pipeline
type: docker
name: "Publish Pipeline"

depends_on:
  - "Build Pipeline"

trigger:
  event:
    - tag

steps:
  - name: BuildArtifacts
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    #failure: ignore
    commands:
      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Install-ModuleDependency;
          Update-ModuleMeta -Verbose
        }"        
      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Install-ModuleDependency;
          New-BuildPackage -Verbose
        }"        

  - name: GiteaRelease
    image: plugins/gitea-release
    settings:
      api_key:
        from_secret: GITEA_TOKEN
      base_url: https://gitea.ocram85.com
      files:
        - "bin/${DRONE_REPO_NAME}.zip"
        - "bin/PSModule.zip"
      title: "${DRONE_TAG}"
      note: CHANGELOG.md

  - name: "PublishModule"
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    #failure: ignore
    environment:
      NuGetToken:
        from_secret: PSGallery
    commands:
      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Install-ModuleDependency;
          Invoke-Publish -Verbose
        }"        

---
kind: pipeline
type: docker
name: "Update Docs"

depends_on:
  - "Build Pipeline"

trigger:
  event:
    exclude:
      - pull_request
  branch:
    include:
      - master

steps:
  - name: "Update Docs"
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    commands:
      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Install-ModuleDependency;
          Update-Docs -Verbose
        }"        

  - name: "push commit"
    image: appleboy/drone-git-push
    settings:
      remote_name: origin
      branch: "droneDocs/${DRONE_COMMIT:0:8}"
      local_ref: droneDocs
      commit: true
      commit_message: "docs updated by drone [CI SKIP]"
      author_name: drone
      author_email: noreply@ocram85.com
      force: true