Skip to content

WIKI Updater Tasks YAML

Jump to bottom Edit New page
rfennell edited this page Apr 9, 2024 · 35 revisions

WIKI Updater Tasks

The 'WIKI Updater Tasks' package contains the following tasks. The table show the possible variables that can be used in YAML Azure DevOps Pipeline configurations

WikiFolderUpdaterTask V2

A tools to update or create a set of files in a folder in WIKI based in a Git repo

YAML snippet

# Git based WIKI Folder Updater from Black Marble
# Description - A tools to update or create a set of files in a folder in WIKI based in a Git repo 
- task: WikiFolderUpdaterTask@2
  inputs: 
     # Required arguments
     repo: 
     targetFolder: 
     replaceFile: True
     appendToFile: True
     sourceFolder: $(build.sourcesdirectory)
     Filter: **/*.md
     message: 
     gitname: 
     gitemail: 
     localpath: $(System.DefaultWorkingDirectory)\repo
     RetryMode: Pull

Arguments

  • Argument: repo
  • Argument: branch
    • Description: The name of the pre-existing branch to checkout prior to committing the change, defaults to empty, so no checkout is done and commits are done to the default 'master' branch
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: targetFolder
    • Description: The name of the folder that the files will be uploaded to
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: replaceFile
    • Description: Replace the file in the WIKI
    • Type: boolean
    • Required: true
    • Default (if defined): True
  • Argument: appendToFile
    • Description: Append to end of file in the WIKI if not replacing file
    • Type: boolean
    • Required: true
    • Default (if defined): True
  • Argument: sourceFolder
    • Description: The source folder to copy from $(build.sourcesdirectory)
    • Type: string
    • Required: true
    • Default (if defined): $(build.sourcesdirectory)
  • Argument: Filter
    • Description: A wildcard expression for the files to upload e.g. **/*.md
    • Type: string
    • Required: true
    • Default (if defined): **/*.md
  • Argument: message
    • Description: The commit message
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: tagRepo
    • Description: If true a tag will be committed to the repo
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: tag
    • Description: Tag text to commit to repo
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: gitname
    • Description: The Git attributes name
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: gitemail
    • Description: The Git attributes email
    • Type: string
    • Required: true
    • Default (if defined):

Authentication

  • Argument: useAgentToken
    • Description: If true use the built in agent OAUTH token. OAUTH script access must be enabled for the agent
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: user
    • Description: The username for authentication
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: password
    • Description: The password/PAT for authentication (recommended stored as secret variable)
    • Type: string
    • Required: false
    • Default (if defined):

Advanced

  • Argument: localpath
    • Description: Path to clone into
    • Type: string
    • Required: true
    • Default (if defined): $(System.DefaultWorkingDirectory)\repo
  • Argument: injectExtraHeader
    • Description: If set to true, credentials are passed as a header value. If false, the default, they are passed in te URL. To address #613 which is seen on some on-prem instances
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: sslBackend
    • Description: Set the http.sslbackend header option (InjectExtraHeader must be set true)
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: retries
    • Description: The number of times to retry if a push fails. After a failed push a pull is run prior to the next attempt
    • Type: string
    • Required: false
    • Default (if defined): 5
  • Argument: RetryMode
    • Description: The Git command used to refresh the cloned repo if the push fails and a retry occurs.
    • Type: pickList
    • Required: true
    • Default (if defined): Pull

WikiFolderUpdaterTask V3

A tools to update or create a set of files in a folder in WIKI based in a Git repo

YAML snippet

# Git based WIKI Folder Updater from Black Marble
# Description - A tools to update or create a set of files in a folder in WIKI based in a Git repo 
- task: WikiFolderUpdaterTask@3
  inputs: 
     # Required arguments
     repo: 
     targetFolder: 
     replaceFile: True
     appendToFile: True
     sourceFolder: $(build.sourcesdirectory)
     Filter: **/*.md
     message: 
     gitname: 
     gitemail: 
     localpath: $(System.DefaultWorkingDirectory)\repo
     RetryMode: Pull

Arguments

  • Argument: repo
  • Argument: branch
    • Description: The name of the pre-existing branch to checkout prior to committing the change, defaults to empty, so no checkout is done and commits are done to the default 'master' branch
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: targetFolder
    • Description: The name of the folder that the files will be uploaded to
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: replaceFile
    • Description: Replace the file in the WIKI
    • Type: boolean
    • Required: true
    • Default (if defined): True
  • Argument: appendToFile
    • Description: Append to end of file in the WIKI if not replacing file
    • Type: boolean
    • Required: true
    • Default (if defined): True
  • Argument: sourceFolder
    • Description: The source folder to copy from $(build.sourcesdirectory)
    • Type: string
    • Required: true
    • Default (if defined): $(build.sourcesdirectory)
  • Argument: Filter
    • Description: A wildcard expression for the files to upload e.g. **/*.md
    • Type: string
    • Required: true
    • Default (if defined): **/*.md
  • Argument: message
    • Description: The commit message
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: tagRepo
    • Description: If true a tag will be committed to the repo
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: tag
    • Description: Tag text to commit to repo
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: gitname
    • Description: The Git attributes name
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: gitemail
    • Description: The Git attributes email
    • Type: string
    • Required: true
    • Default (if defined):

Authentication

  • Argument: useAgentToken
    • Description: If true use the built in agent OAUTH token. OAUTH script access must be enabled for the agent
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: user
    • Description: The username for authentication
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: password
    • Description: The password/PAT for authentication (recommended stored as secret variable)
    • Type: string
    • Required: false
    • Default (if defined):

Advanced

  • Argument: localpath
    • Description: Path to clone into
    • Type: string
    • Required: true
    • Default (if defined): $(System.DefaultWorkingDirectory)\repo
  • Argument: injectExtraHeader
    • Description: If set to true, credentials are passed as a header value. If false, the default, they are passed in te URL. To address #613 which is seen on some on-prem instances
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: sslBackend
    • Description: Set the http.sslbackend header option (InjectExtraHeader must be set true)
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: retries
    • Description: The number of times to retry if a push fails. After a failed push a pull is run prior to the next attempt
    • Type: string
    • Required: false
    • Default (if defined): 5
  • Argument: RetryMode
    • Description: The Git command used to refresh the cloned repo if the push fails and a retry occurs.
    • Type: pickList
    • Required: true
    • Default (if defined): Pull

WikiUpdaterTask V2

A tools to update or create a file in a WIKI based in a Git repo

YAML snippet

# Git based WIKI Single File Updater from Black Marble
# Description - A tools to update or create a file in a WIKI based in a Git repo 
- task: WikiUpdaterTask@2
  inputs: 
     # Required arguments
     repo: 
     filename: 
     replaceFile: True
     appendToFile: True
     contents: 
     sourceFile: 
     message: 
     gitname: 
     gitemail: 
     localpath: $(System.DefaultWorkingDirectory)\repo
     RetryMode: Pull

Arguments

  • Argument: repo
  • Argument: branch
    • Description: The name of the pre-existing branch to checkout prior to committing the change, defaults to empty, so no checkout is done and commits are done to the default 'master' branch
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: filename
    • Description: The name of the file (page) that will be updated or created, must end in .md else it will not appear on the WIKI e.g. page.md
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: replaceFile
    • Description: Replace the file in the WIKI
    • Type: boolean
    • Required: true
    • Default (if defined): True
  • Argument: appendToFile
    • Description: Append to end of file in the WIKI if not replacing file
    • Type: boolean
    • Required: true
    • Default (if defined): True
  • Argument: dataIsFile
    • Description: If true will upload a file, if false the upload is the content provided
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: contents
    • Description: If DataIsFile is false, this text to save in the file, can be the output from another task passed as pipeline variable
    • Type: multiLine
    • Required: true
    • Default (if defined):
  • Argument: sourceFile
    • Description: If DataIsFile is true, this is the filename to upload, will be renamed to the value of the 'filename' parameter
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: message
    • Description: The commit message
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: tagRepo
    • Description: If true a tag will be commited to the repo
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: tag
    • Description: Tag text to commit to repo
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: gitname
    • Description: The Git attributes name
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: gitemail
    • Description: The Git attributes email
    • Type: string
    • Required: true
    • Default (if defined):

Authentication

  • Argument: useAgentToken
    • Description: If true use the built in agent OAUTH token. OAUTH script access must be enabled for the agent
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: user
    • Description: The username for authentication
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: password
    • Description: The password/PAT for authentication (recommended stored as secret variable)
    • Type: string
    • Required: false
    • Default (if defined):

Advanced

  • Argument: localpath
    • Description: Path to clone into
    • Type: string
    • Required: true
    • Default (if defined): $(System.DefaultWorkingDirectory)\repo
  • Argument: injectExtraHeader
    • Description: If set to true, credentials are passed as a header value. If false, the default, they are passed in te URL. To address #613 which is seen on some on-prem instances
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: sslBackend
    • Description: Set the http.sslbackend header option (InjectExtraHeader must be set true)
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: retries
    • Description: The number of times to retry if a push fails. After a failed push a pull is run prior to the next attempt, default of 5
    • Type: string
    • Required: false
    • Default (if defined): 5
  • Argument: trimLeadingSpecialChar
    • Description: The appending or prepending files prior to uploading a leading special character gets added to the file. Setting this flag to true removes this first character.
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: fixLineFeeds
    • Description: If set to true, are swapped to \r\n as this is required for most WIKIs. If false no replacement is made, this should be used for non-text based files e.g. images or PDFs. Only used when replacing the target file
    • Type: boolean
    • Required: false
    • Default (if defined): True
  • Argument: fixSpaces
    • Description: If set to true, and space in the target filename are replaced by -
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: insertLinefeed
    • Description: If set to true, when appending or prepending content a newline is inserted between the old and new content
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: updateOrderFile
    • Description: If set to true, an new line for the uploaded file will be appending, or prepending, in the Azure DevOps WIKI .order file in the root of the repo. If the file does not exist it will be created
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: orderFilePath
    • Description: The path to the folder containing the .order file to update. If empty the .order file in the root of the WIKI will be used.
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: prependEntryToOrderFile
    • Description: If updateOrderFile is set to true, this parameter control whether the new entry is appended (when this is set to false) or prepending (when this is set to true)
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: injecttoc
    • Description: If true will replace the existing [[TOC]] entry in an updated and pre-pended WIKI page with a new one at the top of the revised file (Default: False)
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: RetryMode
    • Description: The Git command used to refresh the cloned repo if the push fails and a retry occurs.
    • Type: pickList
    • Required: true
    • Default (if defined): Pull

WikiUpdaterTask V3

A tools to update or create a file in a WIKI based in a Git repo

YAML snippet

# Git based WIKI Single File Updater from Black Marble
# Description - A tools to update or create a file in a WIKI based in a Git repo 
- task: WikiUpdaterTask@3
  inputs: 
     # Required arguments
     repo: 
     filename: 
     replaceFile: True
     appendToFile: True
     contents: 
     sourceFile: 
     message: 
     gitname: 
     gitemail: 
     localpath: $(System.DefaultWorkingDirectory)\repo
     RetryMode: Pull

Arguments

  • Argument: repo
  • Argument: branch
    • Description: The name of the pre-existing branch to checkout prior to committing the change, defaults to empty, so no checkout is done and commits are done to the default 'master' branch
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: filename
    • Description: The name of the file (page) that will be updated or created, must end in .md else it will not appear on the WIKI e.g. page.md
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: replaceFile
    • Description: Replace the file in the WIKI
    • Type: boolean
    • Required: true
    • Default (if defined): True
  • Argument: appendToFile
    • Description: Append to end of file in the WIKI if not replacing file
    • Type: boolean
    • Required: true
    • Default (if defined): True
  • Argument: dataIsFile
    • Description: If true will upload a file, if false the upload is the content provided
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: contents
    • Description: If DataIsFile is false, this text to save in the file, can be the output from another task passed as pipeline variable
    • Type: multiLine
    • Required: true
    • Default (if defined):
  • Argument: sourceFile
    • Description: If DataIsFile is true, this is the filename to upload, will be renamed to the value of the 'filename' parameter
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: message
    • Description: The commit message
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: tagRepo
    • Description: If true a tag will be commited to the repo
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: tag
    • Description: Tag text to commit to repo
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: gitname
    • Description: The Git attributes name
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: gitemail
    • Description: The Git attributes email
    • Type: string
    • Required: true
    • Default (if defined):

Authentication

  • Argument: useAgentToken
    • Description: If true use the built in agent OAUTH token. OAUTH script access must be enabled for the agent
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: user
    • Description: The username for authentication
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: password
    • Description: The password/PAT for authentication (recommended stored as secret variable)
    • Type: string
    • Required: false
    • Default (if defined):

Advanced

  • Argument: localpath
    • Description: Path to clone into
    • Type: string
    • Required: true
    • Default (if defined): $(System.DefaultWorkingDirectory)\repo
  • Argument: injectExtraHeader
    • Description: If set to true, credentials are passed as a header value. If false, the default, they are passed in te URL. To address #613 which is seen on some on-prem instances
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: sslBackend
    • Description: Set the http.sslbackend header option (InjectExtraHeader must be set true)
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: retries
    • Description: The number of times to retry if a push fails. After a failed push a pull is run prior to the next attempt, default of 5
    • Type: string
    • Required: false
    • Default (if defined): 5
  • Argument: trimLeadingSpecialChar
    • Description: The appending or prepending files prior to uploading a leading special character gets added to the file. Setting this flag to true removes this first character.
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: fixLineFeeds
    • Description: If set to true, are swapped to \r\n as this is required for most WIKIs. If false no replacement is made, this should be used for non-text based files e.g. images or PDFs. Only used when replacing the target file
    • Type: boolean
    • Required: false
    • Default (if defined): True
  • Argument: fixSpaces
    • Description: If set to true, and space in the target filename are replaced by -
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: insertLinefeed
    • Description: If set to true, when appending or prepending content a newline is inserted between the old and new content
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: updateOrderFile
    • Description: If set to true, an new line for the uploaded file will be appending, or prepending, in the Azure DevOps WIKI .order file in the root of the repo. If the file does not exist it will be created
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: orderFilePath
    • Description: The path to the folder containing the .order file to update. If empty the .order file in the root of the WIKI will be used.
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: prependEntryToOrderFile
    • Description: If updateOrderFile is set to true, this parameter control whether the new entry is appended (when this is set to false) or prepending (when this is set to true)
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: injecttoc
    • Description: If true will replace the existing [[TOC]] entry in an updated and pre-pended WIKI page with a new one at the top of the revised file (Default: False)
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: RetryMode
    • Description: The Git command used to refresh the cloned repo if the push fails and a retry occurs.
    • Type: pickList
    • Required: true
    • Default (if defined): Pull

Extension 1 vss-extension.json (Edited for new paths) readme.md license.md images (for extension) logo.png screenshot1.png Task 1 (PowerShell based new layout) src icon.png task.json mytask.ps1 tasklibrary.psm1 (optional as needed) test mytask.tests.ps1

Add a custom sidebar
Clone this wiki locally