Artifacts in Octopus provide a convenient way to collect files from remote machines and copy them to the Octopus Server. Examples of where artifacts may be useful are:
- Collecting log files from other programs.
- Copying configuration files to inspect values.
Artifacts can be collected from anywhere Octopus runs scripts - for example, the Script Console or custom scripts in a deployment.
Artifacts are uploaded to the Octopus Server after a script runs. You can download them from the task output or via the Octopus API.
Collecting artifacts using scripts
You can collect artifacts using any of the scripting languages supported by Octopus. In each scripting language you can specify the path to the file you want to collect as an artifact as an absolute path, or a path relative to the current working directory. By default, the file name will be used as the artifact name, but you can provide a custom name for the artifact as an alternative.
PowerShell
# Collect a custom log file from the current working directory using the file name as the name of the artifact
New-OctopusArtifact "output.log"
# Collect all .xml files contained in the current working directory recursing sub-directories
Get-ChildItem . -Recurse -Include *.xml | New-OctopusArtifact
# Collect the hosts file but using a custom name for each machine so you can differentiate between them
# Note: to collect this artifact would require the Tentacle process to be elevated as a high privileged user account
New-OctopusArtifact -Path "C:\Windows\System32\drivers\etc\hosts" -Name "$([System.Environment]::MachineName)-hosts.txt"
C#
// Collect a custom log file from the current working directory using the file name as the name of the artifact
Octopus.CreateArtifact("output.log");
// Collect the hosts file but using a custom name for each machine so you can differentiate between them
// Note: to collect this artifact would require the Tentacle process to be elevated as a high privileged user account
Octopus.CreateArtifact(@"C:\Windows\System32\drivers\etc\hosts", System.Environment.MachineName + "-hosts.txt");
Bash
# Collect a custom log file from the current working directory using the file name as the name of the artifact
new_octopusartifact output.log
# Collect the hosts file but using a custom name for each machine so you can differentiate between them
# Note: to collect this artifact would require the SSH user account to be elevated as a high privileged user account
new_octopusartifact /etc/hosts $(hostname)-hosts.txt
F#
// Collect a custom log file from the current working directory using the file name as the name of the artifact
Octopus.createArtifact "output.log"
// Collect the hosts file but using a custom name for each machine so you can differentiate between them
// Note: to collect this artifact would require the Tentacle process to be elevated as a high privileged user account
Octopus.createArtifact @"C:\Windows\System32\drivers\etc\hosts" (Some (System.Environment.MachineName + "-hosts.txt"))
Python3
# Collect a custom log file from the current working directory using the file name as the name of the artifact
createartifact("output.log")
# Collect the hosts file but using a custom name for each machine so you can differentiate between them
# Note: to collect this artifact would require the Tentacle process to be elevated as a high privileged user account
import os
createartifact("C:\Windows\System32\drivers\etc\hosts", "{}-hosts.txt".format(os.environ["COMPUTERNAME"]))
Collecting artifacts with execution containers
You can collect artifacts from steps used with the execution container for workers feature too.
The source file for the artifact must be saved and collected from the fully qualified path of one of the directories (or sub-directories) mapped into the execution container as a volume.
The recommended volume to use is the temporary directory created within the <Tentacle Home>/Work workspace, for example, /etc/octopus/Tentacle/Work/20221128114036-119427-56.
Once the artifact has been collected, the directory and its contents will be removed once the step has been executed. Its value can be found in the PWD environment variable.
The following script would collect an artifact called foo.txt from the temporary working directory using the $PWD environment variable:
Bash
echo "Hello" > $PWD/foo.txt
new_octopusartifact $PWD/foo.txt
PowerShell
"Hello" > "$($PWD)/foo.txt"
New-OctopusArtifact "$($PWD)/foo.txt"
Security concerns
File privileges
If you want to collect a file as an artifact, your script must be able to access and read that file. In most cases, files produced by your deployment were produced in the same security context as your running script, and everything will just work. In some cases you may want to collect certain files from the operating system which require elevated privileges, or perhaps a special user account.
If you are using the Tentacle agent, make sure the Tentacle process is running as a user account with access to the file.
If you are using an SSH connection, make sure the SSH user account has access to the file.
Sensitive information
Artifacts are collected by Octopus as-is to maintain the integrity of the files. If the files you want to collect contain sensitive information you should take care to scrub or mask that sensitive information before telling Octopus to collect the artifact.
# Get hold of the variables from Octopus
$username = $OctopusParameters["Database.Username"]
$password = $OctopusParameters["Database.Password"]
$reportFilePath = "upgrade-report.txt"
# Perform the operation as part of your deployment, writing the results to the report file
MyDatabaseUpgrader.exe -reportPath=$reportFilePath
# Scrub sensitive values from report
$mask = '*****'
(Get-Content $reportFilePath) -replace $username, $mask -replace $password, $mask | Set-Content $reportFilePath
# Now collect the scrubbed artifact
New-OctopusArtifact $reportFilePath
Help us continuously improve
Please let us know if you have any feedback about this page.
Page updated on Thursday, December 7, 2023