microsoft/vstsagent.powershell

Tools for managing and automating your Azure DevOps Agents.

VSTS Agent Powershell Module

Tools for managing and automating your Visual Studio Team Services Agents.

Builds

Master

The master branch is automatically built and deployed to the PowerShell Gallery.

Develop

The develop branch is automatically built and deployed as a prerelease module to the PowerShell Gallery.

Installation

Install-Module VSTSAgent -Scope CurrentUser

Using

Cmdlets

Get all of your installed VSTS Agents:

Get-VSTSAgent | Format-Table -AutoSize

# Sample Output
# Id Name    PoolId ServerUrl                          Work                             Service                    Version Path
# -- ----    ------ ---------                          ----                             -------                    ------- ----
# 54 Agent01      1 https://account.visualstudio.com/  file:///D:/VSTSAgentWork/Agent01 vstsagent.account.Agent01  2.138.0 file:///C:/VSTSAgents/Agent01

Install the latest VSTS Agent:

$pat = Read-Host -AsSecureString
Install-VSTSAgent -ServerUrl 'https://account.visualstudio.com' -PAT $pat -Name 'Agent01'

Uninstall any VSTS Agents:

Uninstall-VSTSAgent

Find available VSTS Agents for installation:

Find-VSTSAgent

Start and Stop installed Agents:

Stop-VSTSAgent
Start-VSTSAgent

DSC

VSTSAgent includes the xVSTSAgent DSC Resource. An example configuration might look like:

Configuration Sample_xVSTSAgent_Install {
    param 
    (   
        [parameter(Mandatory = $true)] 
        [PSCredential]$AccountCredential
    )
    Import-DscResource -ModuleName VSTSAgent

    Node 'localhost' {

        xVSTSAgent VSTSAgent {
            Name              = 'Agent01'
            ServerUrl         = 'https://account.visualstudio.com'
            AccountCredential = $AccountCredential
            AgentDirectory    = 'C:\VSTSAgents'
            Work              = 'D:\VSTSAgentsWork\Agent01'
            Ensure            = 'Present'
        }
    }
}

Feedback

To file issues or suggestions, please use the Issues page for this project on GitHub.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Reporting Security Issues

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at [email protected]. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.

vstsagent.powershell's Issues

Nodes became noncompliant in Azure Automation after update

I've recently been looking for ways to automate the configuration of Windows VMs, part of which includes adding build agents, and so glad to have been directed to this project. This may not be the place to raise this issue so please let me know if that is the case.

I've installed the build agent successfully via DSC in Azure Automation. It appears that it was compliant until I updated the agent in DevOps. Once I did that, it became noncompliant in the dashboard and isn't going to return to a compliant state. Does the project have a recommendation for keeping the nodes in a compliant state? Should updating the agents be avoided and the nodes kept up-to-date via some other means? Thanks for any help.

Allow passing proxy settings to agent configuration in Install-VSTSAgent

In case you are running the agent behind a proxy server, you need to pass additional options to the agent configure script as described by https://docs.microsoft.com/en-us/vsts/build-release/actions/agents/proxy?view=vsts

From looking at the Install-VSTSAgent code this does not seem to be supported yet?

Allow specifying capabilities for a VSTS Agent.

Take a list of key value pairs to set as capabilities, i.e. environment variables on the build agent.

PS module failing while trying to download the VSTS agent installer

I am trying to install the VSTS agent using the PS module on remote through through PowerShell on target machines task in the VSTS build pipeline. It is failing while trying to down the package. Need your help regarding fixing this issue

https://vstsagentpackage.azureedge.net/agent/2.155.1/vsts-agent-win-x64-2.155.1.zip
Downloading https://vstsagentpackage.azureedge.net/agent/2.155.1/vsts-agent-win-x64-2.155.1.zip At line:1 char:1

• & 'C:\windows\System32\WindowsPowerShell\v1.0\powershell.exe' -NoLogo ...

•   + CategoryInfo          : NotSpecified: (Downloading htt...64-2.155.1.zip :String) [], RemoteException
    + FullyQualifiedErrorId : NativeCommandError failed: The operation being requested was not performed because the user has not logged on to the network. The specified service does not exist. (Exception from HRESULT: 0x800704DD)
  
  
  

Failed to install VSTS Agent using DSC.

I'm trying to install Agent using DSC but getting an error. Below is the DSC definition I'm using for the local test but keep on failing with error "ConvertTo-MOFInstance : System.InvalidOperationException error processing property 'AccountCredential' OF TYPE 'xVSTSAgent': Converting and storing encrypted passwords as plain
text is not recommended. For more information on securing credentials in MOF file, please refer to MSDN blog: http://go.microsoft.com/fwlink/?LinkId=393729"

on the Azure side the error is "PowerShell DSC resource xVSTSAgent failed to execute Set-TargetResource functionality with error message: Could not find agent matching requirements."

My account that I use to login to DevOps (https://dev.azure.com/CO-Test) has MFA activated so not sure if that is the reason, it keeps on failing.

Configuration InstallVSTSAgent
{
     param 
    (   
        [parameter(Mandatory = $true)] 
        [PSCredential]$AccountCredential
    )
  
    Import-DSCResource -ModuleName 'VSTSAgent'
       
    xVSTSAgent VSTSAgent 
    {  
            Name              = 'Agent01'
            ServerUrl         = 'https://dev.azure.com/CO-Test'
            AccountCredential = $AccountCredential
            AgentDirectory    = 'C:\Agent'
            Work              = 'C:\VSTSAgentsWork\Agent01'
            Ensure            = 'Present' 
    }
}
  # Compile the configuration file to a MOF format
    InstallVSTSAgent

    # Run the configuration on localhost
    Start-DscConfiguration -Path .\InstallVSTSAgent -Wait -Force -Verbose```

A parameter cannot be found that matches parameter name \u0027Attributes\u0027.

Hello Microsoft,
hitting error only first cycle when applying DSC resource xVSTSAgent in azure automation account from module of version 2.0.8. The next 2nd cycle of DSC is successfull. Here is error message:
{
"Exception": {
"Message": "The PowerShell DSC resource \u0027[xVSTSAgent]xVSTSAgent 10\u0027 with SourceInfo \u0027::52::17::xVSTSAgent\u0027 threw one or more non-terminating errors while running the Test-TargetResource functionality. These errors are logged to the ETW channel called Microsoft-Windows-DSC/Operational. Refer to this channel for more details.",
"Data": {

                           },
                  "InnerException":  {
                                         "Message":  "A parameter cannot be found that matches parameter name \u0027Attributes\u0027.",
                                         "ParameterName":  "Attributes",
                                         "ParameterType":  null,
                                         "TypeSpecified":  null,
                                         "ErrorId":  "NamedParameterNotFound",
                                         "Line":  430,
                                         "Offset":  47,
                                         "CommandInvocation":  "System.Management.Automation.InvocationInfo",
                                         "ErrorRecord":  "A parameter cannot be found that matches parameter name \u0027Attributes\u0027.",
                                         "WasThrownFromThrowStatement":  false,
                                         "Data":  "System.Collections.ListDictionaryInternal",
                                         "InnerException":  null,
                                         "TargetSite":  "Void VerifyArgumentsProcessed(System.Management.Automation.ParameterBindingException)",
                                         "StackTrace":  "   at System.Management.Automation.CmdletParameterBinderController.VerifyArgumentsProcessed(ParameterBindingException originalBindingException)\r\n   at System.Management.Automation.CmdletParameterBinderController.BindCommandLineParametersNoValidation(Collection`1 arguments)\r\n   at System.Management.Automation.CmdletParameterBinderController.BindCommandLineParameters(Collection`1 arguments)\r\n   at System.Management.Automation.CommandProcessor.BindCommandLineParameters()\r\n   at System.Management.Automation.CommandProcessorBase.DoPrepare(IDictionary psDefaultParameterValues)\r\n   at System.Management.Automation.Internal.PipelineProcessor.Start(Boolean incomingStream)\r\n   at System.Management.Automation.Internal.PipelineProcessor.SynchronousExecuteEnumerate(Object input)\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Management.Automation.Internal.PipelineProcessor.SynchronousExecuteEnumerate(Object input)\r\n   at System.Management.Automation.PipelineOps.InvokePipeline(Object input, Boolean ignoreInput, CommandParameterInternal[][] pipeElements, CommandBaseAst[] pipeElementAsts, CommandRedirection[][] commandRedirections, FunctionContext funcContext)\r\n   at System.Management.Automation.Interpreter.ActionCallInstruction`6.Run(InterpretedFrame frame)\r\n   at System.Management.Automation.Interpreter.EnterTryCatchFinallyInstruction.Run(InterpretedFrame frame)",
                                         "HelpLink":  null,
                                         "Source":  "System.Management.Automation",
                                         "HResult":  -2146233087
                                     },
                  "TargetSite":  null,
                  "StackTrace":  null,
                  "HelpLink":  null,
                  "Source":  null,
                  "HResult":  -2146233079
              },
"TargetObject":  null,
"CategoryInfo":  {
                     "Category":  7,
                     "Activity":  "",
                     "Reason":  "InvalidOperationException",
                     "TargetName":  "",
                     "TargetType":  ""
                 },
"FullyQualifiedErrorId":  "NonTerminatingErrorFromProvider",
"ErrorDetails":  null,
"InvocationInfo":  null,
"ScriptStackTrace":  null,
"PipelineIterationInfo":  [

                          ]

This repo is missing important files

There are important files that Microsoft projects should all have that are not present in this repository. A pull request has been opened to add the missing file(s). When the pr is merged this issue will be closed automatically.

Microsoft teams can learn more about this effort and share feedback within the open source guidance available internally.

Merge this pull request

Azure DevOps / Azure Pipelines re-brand?

A lot of the other VSTS repo's are being re-branded to Azure DevOps / Azure Pipelines, will this one as well?

No way to specify work folder for agent.

This argument to Install-VSTSAgent should configure the work folder via:

--work <workDirectory>            Work directory where job data is stored. Defaults to _work under the
                                  root of the agent directory. The work directory is owned by a given
                                  agent and should not share between multiple agents.

Install as environment resource

Will these tools support installing the agent as an environment VM resource?

The docs are sparse but pulling from the generated script this seems to mean supporting the options --environment and --environmentname "my-env"

Does replace existing agent keep existing user capabilties?

Install-VSTSAgent has an option to replace an existing agent.
Will existing user capabilities be kept when ‘upgrading’ an agent or will user capabilities need to be manually set again after uninstall/re-install of the agent?

Is TFS supported?

Is TFS also supported by these scripts (and if yes, would it be possible to add some documentation for that?)

Support version for VSTSAgent DSC Resource

Hi,
Currently the latest version, which is used in DSC Resource, 3.220 is in preview. We would like to install 3.218 instead. Could you please add support for versions in DSC resource as you have currently support for it inside the function? I mean Max/min/required versions.

Cannot replace existing agent

When applying DSC second time, the resource will throw the following exception:

Install-VSTSAgent : Cannot configure the agent because it is already configured. To reconfigure th
'config.cmd remove' or './config.sh remove' first.
At line:1 char:1
+ Install-VSTSAgent -Name "Routing build 01" -Pool "Routing" -ServerUrl ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Install-VSTSAgent

This is because -Replace switch in Install-VSTSAgent does not work.
Could uninstalling and then installing the agent be a possible workaround here?

Alert: Nuget API secure token checked in

I hope this token is revoked by now, but it is very good practice not to check this in together with your code.

https://github.com/microsoft/VSTSAgent.PowerShell/blob/be02cac56160e36d71f229a99a08e13c86fde
988/appveyor.yml#L7

Could not find SSL Certificate installation

I could not see the code installing the SSL certificate during the Agent configuration.
Is it possible to include the code to install the SSL certificate in this module?

We are looking to use this module for our requirement to install the agent..

Release management is manual.

Implement it with AppVeyor. CI is CD for master and develop, just like UnitySetup. This is blocked by making the repo public because AppVeyor only works for free on public repos.

Install VSTS Agent using PAT

Hi,

I need to install a VSTS agent inside an Azure VM using a DSC configuration file. As my client's requirement, they want to make use of PAT rather than passing the Account credentials.
Is there any way by which I can use this module to install VSTS agent using PAT? If yes, could you please share with me an example of how to use it.

Thanks in advance.

Support installation of node10-based pipelines-agent in lieu of vsts-agent

Current implementation of Find-VstsAgent filters github releases where assets are prefixed with vsts-agent. Would it be possible to support installation of pipelines-agent through an additional optional string parameter named $AgentType to Install-VstsAgent and Find-VstsAgent? It could have a ValidateSet attribute to limit values to 'vsts-agent' and 'pipelines-agent' but with a default value of 'vsts-agent` to preserve compatibility with DSC code and downstream users. Major difference between the two are outlined here

Missing quotes in specifying args for $configArgs at install-vstsagent

Following piece of code (line 294 - 298 in install-vsts):
[string[]]$configArgs = @('--unattended', '--url', "$ServerUrl", '--auth', ` 'pat', '--pool', "$Pool", '--agent', "$Name", '--runAsService') if ( $Replace ) { $configArgs += '--replace' } if ( $LogonCredential ) { $configArgs += '--windowsLogonAccount', $LogonCredential.UserName } if ( $Work ) { $configArgs += '--work', $Work }
Does not include quotes in the string. For instance "$Pool" will only pass the $Pool parameter and not put it in (single) quotes for the eventual command.

So for instance when passing a Agent pool name like Pool 001 the command line args will be "--pool Pool 001" and not "--pool 'Pool 001'.

Becouse of this the script is not able to handle Agent pools that contain spaces.

Support gmsa when installing agent

@jwittner, Install-VSTSAgent function currently supports installation of agents as a Windows service when LogonCredential parameter is set. We would like to deploy it without needing to provide passwords. GMSAs provide the ability to run Windows services without having to provide/rotate passwords and agent now supports it since this update. I'd like to propose adding this feature to Install-VSTSAgent but before that, would prefer to discuss how to do so with maintainers.

Want to publish the Automation Test Results executed in Azure Devops to team members through(Mail or Teams)

I have developed a testing framework for automating the UWP Application using appium.
Created the build pipeline to run the tests in VM in Azure Devops and able to see the Test Results and summary.

But wanted this results to publish to my entire team of 12 members as soon as the Test Automation in the VM completes through Mail or Microsoft Teams

Can anyone help me on this, if anyone feels any blog or reference would be useful for the above issue. I am reachable @ [email protected]

PAT from $AccountCredential is not working for me

'PAT' = $AccountCredential.Password
it seems like PAT created from AccountCredential is not working

at the end I'm getting this error message. Install-VSTSAgent : VS30063: You are not authorized to access https://dev.azure.com.