Templates

About

Templates are nothing but a simple, yet very powerful feature of this tool. Usually they come very handy when you have a multi-purpose template and you want to use it for different purposes at different times.

Structure

Templates are very similar to normal configuration files except for the fact that they have a command directive within them that lets you assign a command to them during runtime/creation of a new workflow.

PowerShell Command Variable

The command variable is simply a $command format string within the config file. Example: basic-powershellshell.yml.

Writing a template

Lets look at an example. The below template installs the PowerShell module ImportExcel which is a module to import/export Excel spreadsheets, without Excel.

name: Excel Setup

on:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Install ImportExcel PowerShell Module
        shell: pwsh
        run: Install-Module ImportExcel -Force

      - name: Run the scripts
        shell: pwsh
        run: |
$command
      
      - name: Commit and push
        uses: stefanzweifel/git-auto-commit-action@v4.2.0
        with:
          commit_message: Check in Excel results
          commit_user_name: 'PowerShell Automation'

With this template ready, you can name it importexcel.yml and place it in the templates/ folder. Lets execute it!

$command = @'
$url = 'https://raw.githubusercontent.com/dfinke/PSKit/master/sampleCsv/aapl.csv'

Export-Excel -InputObject (Invoke-RestMethod $url | ConvertFrom-Csv) -Path appl.xlsx
'@

Invoke-Advantage dfinke testExcel -template importexcel-powershell -command $command

[*] INFO: Expanding template
[*] INFO: Trying to create repository ...
[+] Successfully created: https://github.com/dfinke/testExcel
[+] Updating workflow
[+] Successfully updated workflow for: importexcel-powershell
[+] Workflow triggered for dfinke/testExcel - getting initial status
[+] Run ID: 586726660

Now you can either clone the repository to see the resultant file appl.xlsx or you can utilize the -saveLogs feature to download the logs!

Its as simple as that. 🤷

Few important things

• The tool uses workflow_dispatch to trigger workflows, so your YAML templates MUST HAVE the workflow dispatch switch.
• GitHub doesn't allow committing files greater than 100MB in size, you can add the following step to prune files just before the committing step in your workflow like the example below:

  - name: Pruning files greater than 100MB
    run: find . -size +99M -delete
  

• Your templates should have the yml extension, GitHub understands YAML config files only.