## 1. Project Overview & Quickstart (sebastienros/serve-cdp) # serve-cdp Open-source repository sebastienros/serve-cdp ### Repository Details - **Repository:** [sebastienros/serve-cdp](https://github.com/sebastienros/serve-cdp) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (sebastienros/website) ## File: src/docs/api/samples/download-artifacts-advanced-ps.md --- title: Downloading AppVeyor build artifacts (PowerShell) layout: docs --- # Downloading AppVeyor build artifacts (PowerShell - advanced example) ```powershell Get-AppVeyorArtifacts ACCOUNT PROJECT -Token TOKEN -Flat ` -DownloadDirectory $env:Temp ` -Proxy http://proxy.example.com:8080/ -ProxyUseDefaultCredentials ``` --- ```powershell function Get-AppVeyorArtifacts { [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Low')] param( #The name of the account you wish to download artifacts from [parameter(Mandatory = $true)] [string]$Account, #The name of the project you wish to download artifacts from [parameter(Mandatory = $true)] [string]$Project, #Where to save the downloaded artifacts. Defaults to current directory. [alias("DownloadDirectory")][string]$Path = '.', [string]$Token, #Filter to a specific branch or project directory. You can specify Branch as either branch name ("master") or build version ("0.1.29") [string]$Branch, #If you have multiple build jobs, specify which job you wish to retrieve the artifacts from [string]$JobName, #Download all files into a single directory, do not preserve any hierarchy that might exist in the artifacts [switch]$Flat, [string]$Proxy, [switch]$ProxyUseDefaultCredentials, #URL of Appveyor API. You normally shouldn't need to change this. $apiUrl = 'https://ci.appveyor.com/api' ) $headers = @{ 'Content-type' = 'application/json' } if ($Token) {$headers.'Authorization' = "Bearer $token"} # Prepare proxy args to splat to Invoke-RestMethod $proxyArgs = @{} if (-not [string]::IsNullOrEmpty($proxy)) { $proxyArgs.Add('Proxy', $proxy) } if ($proxyUseDefaultCredentials.IsPresent) { $proxyArgs.Add('ProxyUseDefaultCredentials', $proxyUseDefaultCredentials) } $errorActionPreference = 'Stop' $projectURI = "$apiUrl/projects/$account/$project" if ($Branch) {$projectURI = $projectURI + "/branch/$Branch"} $projectObject = Invoke-RestMethod -Method Get -Uri $projectURI ` -Headers $headers @proxyArgs if (-not $projectObject.build.jobs) {throw "No jobs found for this project or the project and/or account name was incorrectly specified"} if (($projectObject.build.jobs.count -gt 1) -and -not $jobName) { throw "Multiple Jobs found for the latest build. Please specify the -JobName paramter to select which job you want the artifacts for" } if ($JobName) { $jobid = ($projectObject.build.jobs | Where-Object name -eq "$JobName" | Select-Object -first 1).jobid if (-not $jobId) {throw "Unable to find a job named $JobName within the latest specified build. Did you spell it correctly?"} } else { $jobid = $projectObject.build.jobs[0].jobid } $artifacts = Invoke-RestMethod -Method Get -Uri "$apiUrl/buildjobs/$jobId/artifacts" ` -Headers $headers @proxyArgs $artifacts ` | ? { $psCmdlet.ShouldProcess($_.fileName) } ` | % { $type = $_.type $localArtifactPath = $_.fileName -split '/' | % { [Uri]::UnescapeDataString($_) } if ($flat.IsPresent) { $localArtifactPath = ($localArtifactPath | select -Last 1) } else { $localArtifactPath = $localArtifactPath -join [IO.Path]::DirectorySeparatorChar } $localArtifactPath = Join-Path $path $localArtifactPath $artifactUrl = "$apiUrl/buildjobs/$jobId/artifacts/$($_.fileName)" Write-Verbose "Downloading $artifactUrl to $localArtifactPath" Invoke-RestMethod -Method Get -Uri $artifactUrl -OutFile $localArtifactPath -Headers $headers @proxyArgs New-Object PSObject -Property @{ 'Source' = $artifactUrl 'Type' = $type 'Target' = $localArtifactPath } } } ``` --- ## File: src/docs/api/samples/download-artifacts-ps.md --- title: Downloading AppVeyor build artifacts (PowerShell) layout: docs --- # Downloading AppVeyor build artifacts (PowerShell - basic example) ```powershell $apiUrl = 'https://ci.appveyor.com/api' $token = '' $headers = @{ "Authorization" = "Bearer $token" "Content-type" = "application/json" } $accountName = '' $projectSlug = '' $downloadLocation = 'C:\projects' # get project with last build details $project = Invoke-RestMethod -Method Get -Uri "$apiUrl/projects/$accountName/$projectSlug" -Headers $headers # we assume here that build has a single job # get this job id $jobId = $project.build.jobs[0].jobId # get job artifacts (just to see what we've got) $artifacts = Invoke-RestMethod -Method Get -Uri "$apiUrl/buildjobs/$jobId/artifacts" -Headers $headers # here we just take the first artifact, but you could specify its file name # $artifactFileName = 'MyWebApp.zip' $artifactFileName = $artifacts[0].fileName # artifact will be downloaded as $localArtifactPath = "$downloadLocation\$artifactFileName" # download artifact # -OutFile - is local file name where artifact will be downloaded into # the Headers in this call should only contain the bearer token, and no Content-type, otherwise it will fail! Invoke-RestMethod -Method Get -Uri "$apiUrl/buildjobs/$jobId/artifacts/$artifactFileName" ` -OutFile $localArtifactPath -Headers @{ "Authorization" = "Bearer $token" } ``` --- ## File: src/docs/api/environments-deployments.md --- layout: docs title: Environments and deployments API --- # Environments API ### Environments * [Get environment](#get-environments) * [Get environment settings](#get-environment-settings) * [Get environment deployments](#get-environment-deployments) * [Add environment](#add-environment) * [Update environment](#update-environment) * [Delete environment](#delete-environment) ### Deployments * [Get deployment](#get-deployment) * [Start deployment](#start-deployment) * [Cancel deployment](#cancel-deployment) ## Get environments Request: GET /api/environments Response: ```text [ { "deploymentEnvironmentId": 14, "name": "azure-blob-1", "provider": "AzureBlob", "created": "2014-01-23T18:13:52.2268502+00:00", "updated": "2014-06-02T18:13:32.5106126+00:00" }, { "deploymentEnvironmentId": 12, "name": "azure-deploy-test", "provider": "AzureCS", "created": "2014-01-23T06:46:31.1215919+00:00", "updated": "2014-08-11T18:48:06.2002179+00:00" } ] ``` ## Get environment settings Request: GET /api/environments/{deploymentEnvironmentId}/settings Response: ```text { "environment": { "deploymentEnvironmentId": 14, "name": "azure-blob-1", "provider": "AzureBlob", "environmentAccessKey": "aaabbb12345", "settings": { "providerSettings": [ { "name": "storage_account_name", "value": { "isEncrypted": false, "value": "myaccount" } }, { "name": "storage_access_key", "value": { "isEncrypted": true, "value": "4sc1c7/Qp5buQcZ8N486Ks46mLFbXJVqcJjyv98w==" } }, { "name": "container", "value": { "isEncrypted": false, "value": "test" } }, { "name": "folder", "value": { "isEncrypted": false, "value": "$(APPVEYOR_BUILD_VERSION)" } }, { "name": "artifact", "value": { "isEncrypted": false } } ], "environmentVariables": [] }, "created": "2014-01-23T18:13:52.2268502+00:00", "updated": "2014-06-02T18:13:32.5106126+00:00" } } ``` ## Get environment deployments Request: GET /api/environments/{deploymentEnvironmentId}/deployments Response: ```text { "environment":{ "deploymentEnvironmentId":14, "name":"azure-blob-1", "provider":"AzureBlob", "created":"2014-01-23T18:13:52.2268502+00:00", "updated":"2014-06-02T18:13:32.5106126+00:00" }, "deployments":[ { "project":{ "projectId":15072, "accountId":2, "accountName":"FeodorFitsner", "builds":[ ], "name":"simple-web", "slug":"simple-web", "repositoryType":"gitHub", "repositoryScm":"git", "repositoryName":"AppVeyor/simple-web", "isPrivate":false, "skipBranchesWithoutAppveyorYml":false, "securityDescriptor":{ }, "created":"2014-05-06T16:38:14.7788393+00:00", "updated":"2014-06-02T21:37:30.9378043+00:00" }, "deployment":{ "deploymentId":4120, "build":{ "buildId":18665, "jobs":[ ], "buildNumber":25, "version":"1.0.25", "message":"Merge pull request #3 from FeodorFitsner/master", "messageExtended":"Changes to AccountController", "branch":"master", "commitId":"ed40bd27f732d162b2185d75921b1cd57191f83b", "authorName":"Feodor Fitsner", "authorUsername":"FeodorFitsner", "committerName":"Feodor Fitsner", "committerUsername":"FeodorFitsner", "committed":"2014-05-08T19:11:38+00:00", "messages":[ ], "status":"success", "started":"2014-05-22T20:12:11.4475134+00:00", "finished":"2014-05-22T20:12:33.7806881+00:00", "created":"2014-05-22T20:09:53.759355+00:00", "updated":"2014-05-22T20:12:33.7806881+00:00" }, "environment":{ "deploymentEnvironmentId":14, "name":"azure-blob-1", "provider":"AzureBlob", "created":"2014-01-23T18:13:52.2268502+00:00", "updated":"2014-06-02T18:13:32.5106126+00:00" }, "jobs":[ { "jobId":"1696fh3a2w5ng99y", "name":"Deployment", "messagesCount":0, "status":"success", "started":"2014-07-27T09:59:58.3955159+00:00", "finished":"2014-07-27T10:00:11.5995296+00:00", "created":"2014-07-27T09:59:57.0171035+00:00", "updated":"2014-07-27T10:00:16.163082+00:00" } ], "status":"success", "started":"2014-06-02T18:20:07.9871288+00:00", "finished":"2014-06-02T18:20:25.11916+00:00", "created":"2014-06-02T18:20:07.2833871+00:00", "updated":"2014-06-02T18:20:25.11916+00:00" } } ] } ``` ## Add environment Request: POST /api/environments Request body: ```text { "name":"production", "provider":"FTP", "settings":{ "providerSettings":[ { "name":"server", "value":{ "value":"ftp.myserver.com", "isEncrypted":false } }, { "name":"username", "value":{ "value":"ftp-user", "isEncrypted":false } }, { "name":"password", "value":{ "value":"password", "isEncrypted":true } } ], "environmentVariables":[ { "name":"my-var", "value":{ "value":"123", "isEncrypted":false } } ] } } ``` Response: ```text { "deploymentEnvironmentId":3018, "name":"production", "provider":"FTP", "environmentAccessKey":"gi3ttevuk7a123", "settings":{ "providerSettings":[ { "name":"server", "value":{ "isEncrypted":false, "value":"ftp.myserver.com" } }, { "name":"username", "value":{ "isEncrypted":false, "value":"ftp-user" } }, { "name":"password", "value":{ "isEncrypted":true, "value":"password" } } ], "environmentVariables":[ { "name":"my-var", "value":{ "isEncrypted":false, "value":"123" } } ] }, "created":"2014-08-15T23:57:16.1585268+00:00" } ``` ## Update environment Request: PUT /api/environments Request body: ```text { "deploymentEnvironmentId":3018, "name":"production", "environmentAccessKey":"gi3ttevuk7123", "settings":{ "providerSettings":[ { "name":"server", "value":{ "isEncrypted":false, "value":"ftp.myserver.com" } }, { "name":"username", "value":{ "isEncrypted":false, "value":"ftp-user" } }, { "name":"password", "value":{ "isEncrypted":true, "value":"password" } } ], "environmentVariables":[ { "name":"my-var", "value":{ "isEncrypted":false, "value":"123" } } ], "provider":"FTP" } } ``` Response: ```text { "deploymentEnvironmentId":3018, "name":"production", "provider":"FTP", "environmentAccessKey":"gi3ttevuk7123", "settings":{ "providerSettings":[ { "name":"server", "value":{ "isEncrypted":false, "value":"ftp.myserver.com" } }, { "name":"username", "value":{ "isEncrypted":false, "value":"ftp-user" } }, { "name":"password", "value":{ "isEncrypted":true, "value":"password" } } ], "environmentVariables":[ { "name":"my-var", "value":{ "isEncrypted":false, "value":"123" } } ] }, "created":"2014-08-15T23:57:16.1585268+00:00", "updated":"2014-08-16T00:00:37.6079863+00:00" } ``` ## Delete environment Request: DELETE /api/environments/{deploymentEnvironmentId} Response: 204 ### Get deployment Request: GET /api/deployments/{deploymentId} Response: ```text { "project":{ "projectId":22321, "accountId":2, "accountName":"appvyr", "builds":[ ], "name":"simple-web", "slug":"simple-web", "repositoryType":"gitHub", "repositoryScm":"git", "repositoryName":"AppVeyor/simple-web", "isPrivate":false, "skipBranchesWithoutAppveyorYml":false, "securityDescriptor":{ }, "created":"2014-05-08T18:38:57.9163293+00:00", "updated":"2014-07-14T10:16:26.9351867+00:00" }, "deployment":{ "deploymentId":19475, "build":{ "buildId":132746, "jobs":[ ], "buildNumber":38, "version":"1.0.38", "message":"Removed Start-Website", "branch":"master", "commitId":"c397ba5d17dd17b994375405f560e4922207da1e", "authorName":"Feodor Fitsner", "authorUsername":"FeodorFitsner", "committerName":"Feodor Fitsner", "committerUsername":"FeodorFitsner", "committed":"2014-08-12T22:56:00+00:00", "messages":[ ], "status":"success", "started":"2014-08-12T22:56:25.8575967+00:00", "finished":"2014-08-12T22:58:05.7595508+00:00", "created":"2014-08-12T22:56:09.9208493+00:00", "updated":"2014-08-12T22:58:05.7595508+00:00" }, "environment":{ "deploymentEnvironmentId":27, "name":"agent test", "provider":"Agent", "created":"2014-04-01T17:56:41.30982+00:00", "updated":"2014-08-12T22:35:51.9723883+00:00" }, "jobs":[ { "jobId":"jnpbcc77s4w278e4", "name":"Deployment", "messagesCount":0, "status":"success", "started":"2014-08-12T23:06:10.8776088+00:00", "finished":"2014-08-12T23:06:24.3361102+00:00", "created":"2014-08-12T23:06:07.9009315+00:00", "updated":"2014-08-12T23:06:24.9390847+00:00" } ], "status":"success", "started":"2014-08-12T23:06:10.8776088+00:00", "finished":"2014-08-12T23:06:25.0502019+00:00", "created":"2014-08-12T23:06:07.9009315+00:00", "updated":"2014-08-12T23:06:25.0502019+00:00" } } ``` ### Start deployment Request: POST /api/deployments Request body: ```text { "environmentName": "environment-to-deploy", "accountName": "your-account-name", "projectSlug": "project-slug-from-url", "buildVersion": "1.2.0", # build to deploy "buildJobId": "sfke9239ydzf", # optional job id with artifacts if build contains multiple jobs "environmentVariables": { "server": "myserver.com", "another_var": "another value" } } ``` Response: ```text { "deploymentId":19475, "build":{ "buildId":132746, "jobs":[ ], "buildNumber":38, "version":"1.0.38", "message":"Removed Start-Website", "branch":"master", "commitId":"c397ba5d17dd17b994375405f560e4922207da1e", "authorName":"Feodor Fitsner", "authorUsername":"FeodorFitsner", "committerName":"Feodor Fitsner", "committerUsername":"FeodorFitsner", "committed":"2014-08-12T22:56:00+00:00", "messages":[ ], "status":"success", "started":"2014-08-12T22:56:25.8575967+00:00", "finished":"2014-08-12T22:58:05.7595508+00:00", "created":"2014-08-12T22:56:09.9208493+00:00", "updated":"2014-08-12T22:58:05.7595508+00:00" }, "environment":{ "deploymentEnvironmentId":27, "name":"agent test", "provider":"Agent", "created":"2014-04-01T17:56:41.30982+00:00", "updated":"2014-08-12T22:35:51.9723883+00:00" }, "jobs":[ { "jobId":"jnpbcc77s4w278e4", "name":"Deployment", "messagesCount":0, "status":"success", "started":"2014-08-12T23:06:10.8776088+00:00", "finished":"2014-08-12T23:06:24.3361102+00:00", "created":"2014-08-12T23:06:07.9009315+00:00", "updated":"2014-08-12T23:06:24.9390847+00:00" } ], "status":"success", "started":"2014-08-12T23:06:10.8776088+00:00", "finished":"2014-08-12T23:06:25.0502019+00:00", "created":"2014-08-12T23:06:07.9009315+00:00", "updated":"2014-08-12T23:06:25.0502019+00:00" } ``` ### Cancel deployment Request: PUT /api/deployments/stop Request body: ```text { deploymentId: 123 } ``` Response: 204 --- ## File: src/docs/api/index.md --- layout: docs title: AppVeyor REST API --- # Overview APIs: * [Teams (Users, Roles, Collaborators)](/docs/api/team/) * [Projects and Builds](/docs/api/projects-builds/) * [Environments and Deployments](/docs/api/environments-deployments/) Samples: * [Downloading build artifact (PowerShell - basic example)](/docs/api/samples/download-artifacts-ps/) * [Downloading build artifact (PowerShell - advanced example)](/docs/api/samples/download-artifacts-advanced-ps/) ## Authentication AppVeyor uses bearer token authentication. Token can be found on [API token page](https://ci.appveyor.com/api-keys) under your AppVeyor account. Token must be set in `Authorization` header of every request to AppVeyor REST API: Authorization: Bearer Default content type is JSON, but if you need to return XML set `Accept` header: Accept: application/xml ## Samples ### PowerShell The following PowerShell code uses standard `Invoke-RestMethod` cmdlet to return the list of roles from authenticated account: ```powershell $token = '' $headers = @{} $headers['Authorization'] = "Bearer $token" $headers["Content-type"] = "application/json" Invoke-RestMethod -Uri 'https://ci.appveyor.com/api/roles' -Headers $headers -Method Get ``` ### C\# The following code sample uses `HttpClient` class from `Microsoft.AspNet.WebApi.Client` NuGet package to get the list of roles from authenticated account: ```csharp string token = ""; using(var client = new HttpClient()) { client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json")); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token); // get the list of roles using (var response = await client.GetAsync("https://ci.appveyor.com/api/roles")) { response.EnsureSuccessStatusCode(); var roles = await response.Content.ReadAsAsync(); foreach (var role in roles) { Console.WriteLine(role.Value("name")); } } } ``` ### curl The following command uses `curl` to get the list of roles from authenticated account: ```bash export APPVEYOR_TOKEN="" curl -H "Authorization: Bearer $APPVEYOR_TOKEN" -H "Content-Type: application/json" https://ci.appveyor.com/api/roles ``` **Note.** If you plan to download artifacts with curl you should update curl up to 7.58.0. Otherwise curl wont be able to download artifacts due to CVE-2018-1000007. --- ## File: src/docs/api/projects-builds.md --- layout: docs title: Projects and builds API --- # Projects * [Get projects](#get-projects) * [Get project last build](#get-project-last-build) * [Get project last branch build](#get-project-last-branch-build) * [Get project build by version](#get-project-build-by-version) * [Get project history](#get-project-history) * [Get project deployments](#get-project-deployments) * [Get project settings](#get-project-settings) * [Get project settings in YAML](#get-project-settings-in-yaml) * [Get project environment variables](#get-project-environment-variables) * [Add project](#add-project) * [Update project](#update-project) * [Update project settings in YAML](#update-project-settings-in-yaml) * [Update project environment variables](#update-project-environment-variables) * [Update project build number](#update-project-build-number) * [Delete project build cache](#delete-project-build-cache) * [Delete project](#delete-project) # Builds * [Start build of branch most recent commit](#start-build-of-branch-most-recent-commit) * [Start build of specific branch commit](#start-build-of-specific-branch-commit) * [Re-run build](#re-run-build) * [Start build of Pull Request](#start-build-of-pull-request) * [Cancel build](#cancel-build) * [Delete build](#delete-build) # Build Jobs * [Download build log](#download-build-log) ## Get projects Request: GET /api/projects Response: ```text [ { "projectId":19096, "accountId":2, "accountName":"FeodorFitsner", "builds":[ { "buildId":23864, "jobs":[ ], "buildNumber":3, "version":"1.0.3", "message":"replaced with command [skip ci]", "branch":"master", "commitId":"c2892a70d60c96c1b65a7c665ab806b7731fea8a", "authorName":"Feodor Fitsner", "authorUsername":"FeodorFitsner", "committerName":"Feodor Fitsner", "committerUsername":"FeodorFitsner", "committed":"2014-08-15T22:05:54+00:00", "messages":[ ], "status":"success", "started":"2014-08-15T22:36:38.1757886+00:00", "finished":"2014-08-15T22:37:00.6171479+00:00", "created":"2014-08-15T22:33:15.9833328+00:00", "updated":"2014-08-15T22:37:00.6171479+00:00" } ], "name":"appveyor-artifact-test", "slug":"appveyor-artifact-test", "repositoryType":"gitHub", "repositoryScm":"git", "repositoryName":"FeodorFitsner/appveyor-artifact-test", "repositoryBranch":"master", "isPrivate":false, "skipBranchesWithoutAppveyorYml":false, "nuGetFeed":{ "id":"appveyor-artifact-test-j8kk0o", "name":"Project appveyor-artifact-test", "publishingEnabled":false, "created":"2014-08-15T22:04:21.3111546+00:00" }, "created":"2014-08-15T22:04:19.2868375+00:00" } ] ``` ## Get project last build Request: GET /api/projects/{accountName}/{projectSlug} Response: ```text { "project":{ "projectId":38907, "accountId":2, "accountName":"appvyr", "builds":[ ], "name":"nuget-test", "slug":"nuget-test", "repositoryType":"gitHub", "repositoryScm":"git", "repositoryName":"FeodorFitsner/nuget-test", "repositoryBranch":"master", "isPrivate":false, "skipBranchesWithoutAppveyorYml":false, "nuGetFeed":{ "id":"nuget-test-23spw2w", "name":"Project nuget-test", "publishingEnabled":false, "created":"2014-07-19T10:23:05.5160273+00:00" }, "securityDescriptor":{ }, "created":"2014-07-19T10:23:03.8005134+00:00", "updated":"2014-08-01T05:25:15.4119745+00:00" }, "build":{ "buildId":134173, "jobs":[ { "jobId":"9r2qufuu8", "name":"", "allowFailure":false, "messagesCount":0, "compilationMessagesCount":0, "compilationErrorsCount":0, "compilationWarningsCount":0, "testsCount":0, "passedTestsCount":0, "failedTestsCount":0, "artifactsCount":0, "status":"success", "started":"2014-08-14T05:41:49.1061831+00:00", "finished":"2014-08-14T05:42:45.1102797+00:00", "created":"2014-08-14T05:39:27.3902557+00:00", "updated":"2014-08-14T05:42:45.477213+00:00" } ], "buildNumber":45, "version":"1.0.45", "message":"AssemblyInfo patching", "branch":"master", "commitId":"85da1fb810ae89744abad83e75c13483dd740258", "authorName":"Feodor Fitsner", "authorUsername":"FeodorFitsner", "committerName":"Feodor Fitsner", "committerUsername":"FeodorFitsner", "committed":"2014-07-03T07:56:15+00:00", "messages":[ ], "status":"success", "started":"2014-08-14T05:41:49.1686804+00:00", "finished":"2014-08-14T05:42:45.5709599+00:00", "created":"2014-08-14T05:39:26.2946368+00:00", "updated":"2014-08-14T05:42:45.5709599+00:00" } } ``` ## Get project last branch build Request: GET /api/projects/{accountName}/{projectSlug}/branch/{buildBranch} Response: Response is the same as [Get project last build](#get-project-last-build) ## Get project build by version Request: GET /api/projects/{accountName}/{projectSlug}/build/{buildVersion} Response: Response is the same as [Get project last build](#get-project-last-build) ## Get project history Request: GET /api/projects/{accountName}/{projectSlug}/history?recordsNumber={records-per-page}[&startBuildId={buildId}&branch={branch}] Response: ```text { "project":{ "projectId":42438, "accountId":2, "accountName":"appvyr", "builds":[ ], "name":"wix-test", "slug":"wix-test", "repositoryType":"gitHub", "repositoryScm":"git", "repositoryName":"FeodorFitsner/wix-test", "isPrivate":false, "skipBranchesWithoutAppveyorYml":false, "created":"2014-08-09T00:30:43.3327131+00:00" }, "builds":[ { "buildId":134174, "jobs":[ ], "buildNumber":5, "version":"1.0.5", "message":"Enabled diag mode", "branch":"master", "commitId":"d19740243e3ec5497345de0f7d828e66a7cd1a6b", "authorName":"Feodor Fitsner", "authorUsername":"FeodorFitsner", "committerName":"Feodor Fitsner", "committerUsername":"FeodorFitsner", "committed":"2014-08-10T14:08:16+00:00", "messages":[ ], "status":"success", "started":"2014-08-14T05:42:17.2696755+00:00", "finished":"2014-08-14T05:43:47.4732355+00:00", "created":"2014-08-14T05:39:30.8845902+00:00", "updated":"2014-08-14T05:43:47.4732355+00:00" }, { "buildId":129289, "jobs":[ ], "buildNumber":3, "version":"1.0.3", "message":"Added appveyor.yml", "branch":"master", "commitId":"28c6eec932c0e21eca5bb5571a722f850aa8bf6f", "authorName":"Feodor Fitsner", "authorUsername":"FeodorFitsner", "committerName":"Feodor Fitsner", "committerUsername":"FeodorFitsner", "committed":"2014-08-09T00:33:34+00:00", "messages":[ ], "status":"success", "started":"2014-08-09T15:42:45.7878479+00:00", "finished":"2014-08-09T15:44:15.5828009+00:00", "created":"2014-08-09T15:42:38.8315273+00:00", "updated":"2014-08-09T15:44:15.5828009+00:00" } ] } ``` ## Get project deployments Request: GET /api/projects/{accountName}/{projectSlug}/deployments[?recordsNumber={records-per-page}&startDeploymentId={deploymentId}] Note: maximum and default `recordsNumber` is 20. Response: ```text { "project":{ "projectId":22321, "accountId":2, "accountName":"appvyr", "builds":[ ], "name":"simple-web", "slug":"simple-web", "repositoryType":"gitHub", "repositoryScm":"git", "repositoryName":"AppVeyor/simple-web", "isPrivate":false, "skipBranchesWithoutAppveyorYml":false, "securityDescriptor":{ }, "created":"2014-05-08T18:38:57.9163293+00:00", "updated":"2014-07-14T10:16:26.9351867+00:00" }, "deployments":[ { "environment":{ "deploymentEnvironmentId":27, "name":"agent test", "provider":"Agent", "created":"2014-04-01T17:56:41.30982+00:00", "updated":"2014-08-12T22:35:51.9723883+00:00" }, "deployment":{ "deploymentId":19475, "build":{ "buildId":132746, "jobs":[ ], "buildNumber":38, "version":"1.0.38", "message":"Removed Start-Website", "branch":"master", "commitId":"c397ba5d17dd17b994375405f560e4922207da1e", "authorName":"Feodor Fitsner", "authorUsername":"FeodorFitsner", "committerName":"Feodor Fitsner", "committerUsername":"FeodorFitsner", "committed":"2014-08-12T22:56:00+00:00", "messages":[ ], "status":"success", "started":"2014-08-12T22:56:25.8575967+00:00", "finished":"2014-08-12T22:58:05.7595508+00:00", "created":"2014-08-12T22:56:09.9208493+00:00", "updated":"2014-08-12T22:58:05.7595508+00:00" }, "environment":{ "deploymentEnvironmentId":27, "name":"agent test", "provider":"Agent", "created":"2014-04-01T17:56:41.30982+00:00", "updated":"2014-08-12T22:35:51.9723883+00:00" }, "jobs":[ { "jobId":"jnpbcc77s4w278e4", "name":"Deployment", "messagesCount":0, "status":"success", "started":"2014-08-12T23:06:10.8776088+00:00", "finished":"2014-08-12T23:06:24.3361102+00:00", "created":"2014-08-12T23:06:07.9009315+00:00", "updated":"2014-08-12T23:06:24.9390847+00:00" }, { "jobId":"nbgyf7pn65d4agyr", "name":"TEST-AGENT-DEPL", "messagesCount":0, "status":"success", "started":"2014-08-12T23:06:14.8148958+00:00", "finished":"2014-08-12T23:06:21.9647266+00:00", "created":"2014-08-12T23:06:14.8148958+00:00", "updated":"2014-08-12T23:06:22.3768791+00:00" } ], "status":"success", "started":"2014-08-12T23:06:10.8776088+00:00", "finished":"2014-08-12T23:06:25.0502019+00:00", "created":"2014-08-12T23:06:07.9009315+00:00", "updated":"2014-08-12T23:06:25.0502019+00:00" } } ] } ``` ## Get project settings Request: GET /api/projects/{accountName}/{projectSlug}/settings Response: ```text { "project":{ "projectId":22321, "accountId":2, "accountName":"appvyr", "builds":[ ], "name":"simple-web", "slug":"simple-web", "repositoryType":"gitHub", "repositoryScm":"git", "repositoryName":"AppVeyor/simple-web", "isPrivate":false, "skipBranchesWithoutAppveyorYml":false, "securityDescriptor":{ "accessRightDefinitions":[ { "name":"View", "description":"View" }, { "name":"RunBuild", "description":"Run build" }, { "name":"Update", "description":"Update settings" }, { "name":"Delete", "description":"Delete project" } ], "roleAces":[ { "roleId":4, "name":"Administrator", "isAdmin":true, "accessRights":[ { "name":"View", "allowed":true }, { "name":"RunBuild", "allowed":true }, { "name":"Update", "allowed":true }, { "name":"Delete", "allowed":true } ] }, { "roleId":5, "name":"User", "isAdmin":false, "accessRights":[ { "name":"View" }, { "name":"RunBuild" }, { "name":"Update" }, { "name":"Delete" } ] } ] }, "created":"2014-05-08T18:38:57.9163293+00:00", "updated":"2014-07-14T10:16:26.9351867+00:00" }, "settings":{ "projectId":22321, "accountId":2, "accountName":"appvyr", "builds":[ ], "name":"simple-web", "slug":"simple-web", "versionFormat":"1.0.{build}", "nextBuildNumber":41, "repositoryType":"gitHub", "repositoryScm":"git", "repositoryName":"AppVeyor/simple-web", "repositoryBranch":"master", "webhookId":"k783di7br", "webhookUrl":"https://ci.appveyor.com/api/github/webhook?id=k783di7br", "isPrivate":false, "ignoreAppveyorYml":false, "skipBranchesWithoutAppveyorYml":false, "configuration":{ "initScripts":[], "includeBranches":[], "excludeBranches":[], "onBuildSuccessScripts":[], "onBuildErrorScripts":[], "patchAssemblyInfo":false, "assemblyInfoFile":"**\\AssemblyInfo.*", "assemblyVersionFormat":"{version}", "assemblyFileVersionFormat":"{version}", "assemblyInformationalVersionFormat":"{version}", "operatingSystem":[], "services":[], "shallowClone":false, "environmentVariables":[], "environmentVariablesMatrix":[], "installScripts":[], "hostsEntries":[], "buildMode":"msbuild", "platform":[], "configuration":[], "packageWebApplicationProjects":false, "packageWebApplicationProjectsXCopy":false, "packageAzureCloudServiceProjects":false, "packageNuGetProjects":false, "msBuildVerbosity":"minimal", "buildScripts":[], "beforeBuildScripts":[], "afterBuildScripts":[], "testMode":"auto", "testAssemblies":[], "testCategories":[], "testCategoriesMatrix":[], "testScripts":[], "beforeTestScripts":[], "afterTestScripts":[], "deployMode":"providers", "deployments":[], "deployScripts":[], "beforeDeployScripts":[], "afterDeployScripts":[], "matrixFastFinish":false, "matrixAllowFailures":[], "artifacts":[], "notifications":[] }, "nuGetFeed":{ "id":"simple-web-0r50wgb1st6q", "name":"Project simple-web", "publishingEnabled":false, "created":"2014-05-08T18:38:59.2455842+00:00" }, "securityDescriptor":{ "accessRightDefinitions":[ { "name":"View", "description":"View" }, { "name":"RunBuild", "description":"Run build" }, { "name":"Update", "description":"Update settings" }, { "name":"Delete", "description":"Delete project" } ], "roleAces":[ { "roleId":4, "name":"Administrator", "isAdmin":true, "accessRights":[ { "name":"View", "allowed":true }, { "name":"RunBuild", "allowed":true }, { "name":"Update", "allowed":true }, { "name":"Delete", "allowed":true } ] }, { "roleId":5, "name":"User", "isAdmin":false, "accessRights":[ { "name":"View" }, { "name":"RunBuild" }, { "name":"Update" }, { "name":"Delete" } ] } ] }, "created":"2014-05-08T18:38:57.9163293+00:00", "updated":"2014-07-14T10:16:26.9351867+00:00" }, "images":[ { "name":"test-win2012-r2" }, { "name":"Windows Server 2012" }, { "name":"Windows Server 2012 R2" } ] } ``` ## Get project settings in YAML Request: GET /api/projects/{accountName}/{projectSlug}/settings/yaml Response (`plain/text`): ```text version: 1.0.{build} build: project: MySolution.sln verbosity: minimal publish_wap: true ... ``` ## Get project environment variables Request: GET /api/projects/{accountName}/{projectSlug}/settings/environment-variables Response: ```text [ { "name":"api_key", "value":{ "isEncrypted":true, "value":"very-secret-key-in-clear-text" } }, { "name":"var1", "value":{ "isEncrypted":false, "value":"current-value" } } ] ``` ## Add project Request: POST /api/projects Request body: ```text { "repositoryProvider":"gitHub", "repositoryName":"FeodorFitsner/demo-app" } ``` Where `repositoryProvider` is one of: * `gitHub` * `bitBucket` * `vso` (Visual Studio Online) * `gitLab` * `kiln` * `stash` * `git` * `mercurial` * `subversion` Response: ```text { "projectId":43682, "accountId":2, "accountName":"appvyr", "builds":[ ], "name":"demo-app", "slug":"demo-app-335", "repositoryType":"gitHub", "repositoryScm":"git", "repositoryName":"FeodorFitsner/demo-app", "isPrivate":false, "skipBranchesWithoutAppveyorYml":false, "created":"2014-08-16T00:52:15.6604826+00:00" } ``` ## Update project Request: PUT /api/projects Request body: ```text { "projectId":43682, "accountId":2, "accountName":"appvyr", "builds":[], "name":"demo-app", "slug":"demo-app-335", "versionFormat":"1.0.{build}", "nextBuildNumber":1, "repositoryType":"gitHub", "repositoryScm":"git", "repositoryName":"FeodorFitsner/demo-app", "repositoryBranch":"master", "webhookId":"rca5vb5qqu", "webhookUrl":"https://ci.appveyor.com/api/github/webhook?id=rca5vb5qqu", "isPrivate":false, "ignoreAppveyorYml":false, "skipBranchesWithoutAppveyorYml":false, "configuration":{ "initScripts":[], "includeBranches":[], "excludeBranches":[], "onBuildSuccessScripts":[], "onBuildErrorScripts":[], "patchAssemblyInfo":false, "assemblyInfoFile":"**\\AssemblyInfo.*", "assemblyVersionFormat":"{version}", "assemblyFileVersionFormat":"{version}", "assemblyInformationalVersionFormat":"{version}", "operatingSystem":[], "services":[], "shallowClone":false, "environmentVariables":[], "environmentVariablesMatrix":[], "installScripts":[], "hostsEntries":[], "buildMode":"msbuild", "platform":[], "configuration":[], "packageWebApplicationProjects":false, "packageWebApplicationProjectsXCopy":false, "packageAzureCloudServiceProjects":false, "packageNuGetProjects":false, "msBuildVerbosity":"minimal", "buildScripts":[], "beforeBuildScripts":[], "afterBuildScripts":[], "testMode":"auto", "testAssemblies":[], "testCategories":[], "testCategoriesMatrix":[], "testScripts":[], "beforeTestScripts":[], "afterTestScripts":[], "deployMode":"providers", "deployments":[], "deployScripts":[], "beforeDeployScripts":[], "afterDeployScripts":[], "matrixFastFinish":false, "matrixAllowFailures":[], "artifacts":[], "notifications":[] }, "nuGetFeed":{ "id":"demo-app-tw5iw2wk3bl1", "name":"Project demo-app", "publishingEnabled":false, "created":"2014-08-16T00:52:16.9886427+00:00" }, "securityDescriptor":{ "accessRightDefinitions":[ { "name":"View", "description":"View" }, { "name":"RunBuild", "description":"Run build" }, { "name":"Update", "description":"Update settings" }, { "name":"Delete", "description":"Delete project" } ], "roleAces":[ { "roleId":4, "name":"Administrator", "isAdmin":true, "accessRights":[ { "name":"View", "allowed":true }, { "name":"RunBuild", "allowed":true }, { "name":"Update", "allowed":true }, { "name":"Delete", "allowed":true } ] }, { "roleId":5, "name":"User", "isAdmin":false, "accessRights":[ { "name":"View" }, { "name":"RunBuild" }, { "name":"Update" }, { "name":"Delete" } ] } ] }, "created":"2014-08-16T00:52:15.6604826+00:00" } ``` Response: 204 ## Update project settings in YAML Request: PUT /api/projects/{accountName}/{projectSlug}/settings/yaml Request body (`plain/text`): ```text version: 1.0.{build} build: project: MySolution.sln verbosity: minimal publish_wap: true ... ``` Response: 204 ## Update project environment variables Request: PUT /api/projects/{accountName}/{projectSlug}/settings/environment-variables Request body (`application/json`): ```text [ { "name":"api_key", "value":{ "isEncrypted":true, "value":"very-secret-key-encrypted" } }, { "name":"var1", "value":{ "isEncrypted":false, "value":"new-value" } } ] ``` Response: 204 ## Update project build number Request: PUT /api/projects/{accountName}/{projectSlug}/settings/build-number Request body (`application/json`): ```text { "nextBuildNumber": 35 } ``` Response: 204 ## Delete project build cache Request: DELETE /api/projects/{accountName}/{projectSlug}/buildcache Response: 204 ## Delete project Request: DELETE /api/projects/{accountName}/{projectSlug} Response: 204 ### Start build of branch most recent commit Request: POST /api/builds Request body: ```text { "accountName": "your-account-name", "projectSlug": "project-slug-from-url", "branch": "master", "environmentVariables": { "my_var": "value", "another_var": "another value" } } ``` Response: ```text { "buildId":136709, "jobs":[ ], "buildNumber":7, "version":"1.0.7", "message":"replaced with command [skip ci]", "branch":"master", "commitId":"c2892a70d60c96c1b65a7c665ab806b7731fea8a", "authorName":"Feodor Fitsner", "authorUsername":"FeodorFitsner", "committerName":"Feodor Fitsner", "committerUsername":"FeodorFitsner", "committed":"2014-08-15T22:05:54+00:00", "messages":[ ], "status":"queued", "created":"2014-08-16T00:40:38.1703914+00:00" } ``` ### Start build of specific branch commit Request: POST /api/builds Request body: ```text { "accountName": "your-account-name", "projectSlug": "project-slug-from-url", "branch": "develop", "commitId": "3e9d9468" } ``` ### Re-run build Request: PUT /api/builds Request body: ```text { buildId: {buildId}, reRunIncomplete: {True/False} } ``` Set `reRunIncomplete` set to `False` (default value) for full buildre-run. Set it set to `True` to rerun only failed or cancelled jobs in multijob build. ### Start build of Pull Request Request: POST /api/builds Request body: ```text { accountName: 'your-account-name', projectSlug: 'project-slug-from-url', pullRequestId: 3 } ``` Response body: ```text { "buildId":642688, "jobs":[], "buildNumber":308, "version":"308", "message":"...", "branch":"master", "isTag":false, "commitId":"3a9e50dfb4dbf3c463b57ffd6453bf9cc103bcff", "authorName":"...", "authorUsername":"...", "committerName":"...", "committerUsername":"...", "committed":"2015-03-29T06:59:41+00:00", "pullRequestId":"86", "pullRequestName":"...", "messages":[], "status":"queued", "created":"2015-03-29T19:49:00.2126257+00:00" } ``` ### Cancel build Request: DELETE /api/builds/{accountName}/{projectSlug}/{buildVersion} Response: 204 ### Delete build Request: DELETE /api/builds/{buildId} Response: 204 ### Download build log Request: GET /api/buildjobs/{jobId}/log Response: Text file with the log. --- ## File: src/docs/api/team.md --- layout: docs title: Team API --- # Team ### Users * [Get users](#get-users) * [Get user](#get-user) * [Add user](#add-user) * [Update user](#update-user) * [Delete user](#delete-user) ### Collaborators * [Get collaborators](#get-collaborators) * [Get collaborator](#get-collaborator) * [Add collaborator](#add-collaborator) * [Update collaborator](#update-collaborator) * [Delete collaborator](#delete-collaborator) ### Roles * [Get roles](#get-roles) * [Get role](#get-role) * [Add role](#add-role) * [Update role](#update-role) * [Delete role](#delete-role) ## Get users Request: GET /api/users Response: ```text [ { "accountId":2, "accountName":"FeodorFitsner", "isOwner":false, "isCollaborator":false, "userId":2019, "fullName":"NuGet", "email":"nuget@appveyor.com", "roleId":5, "roleName":"User", "successfulBuildNotification":"all", "failedBuildNotification":"all", "notifyWhenBuildStatusChangedOnly":true, "created":"2014-02-12T19:21:15.0618564+00:00", "updated":"2014-03-06T22:47:44.9706252+00:00" } ] ``` ## Get user Request: GET /api/users/{userId} Response: ```text { "user":{ "accountId":2, "accountName":"FeodorFitsner", "isOwner":false, "isCollaborator":false, "userId":2019, "fullName":"NuGet", "email":"nuget@appveyor.com", "roleId":5, "roleName":"User", "successfulBuildNotification":"all", "failedBuildNotification":"all", "notifyWhenBuildStatusChangedOnly": true, "successfulDeploymentNotification": "all", "failedDeploymentNotification": "all", "notifyWhenBuildStatusChangedOnly":true, "created":"2014-02-12T19:21:15.0618564+00:00", "updated":"2014-03-06T22:47:44.9706252+00:00" }, "roles":[ { "roleId":4, "name":"Administrator", "isSystem":true, "created":"2013-09-26T19:23:39.3615105+00:00" }, { "roleId":5, "name":"User", "isSystem":true, "created":"2013-09-26T19:23:39.3645117+00:00" } ] } ``` ## Add user Request: POST /api/users Request body: ```text { "fullName":"John Smith", "email":"john@smith.com", "roleId":4, "generatePassword":false, "password":"password", "confirmPassword":"password" } ``` Response: 204 ## Update user Request: PUT /api/users Request body: ```text { "userId":3019, "fullName":"John Smith", "email":"john@smith.com", "password": null, "roleId":4, "successfulBuildNotification":"all", "failedBuildNotification":"all", "notifyWhenBuildStatusChangedOnly": true, "successfulDeploymentNotification":"all", "failedDeploymentNotification":"all", "notifyWhenBuildStatusChangedOnly":true } ``` Response: 204 ## Delete user Request: DELETE /api/users/{userId} Response: 204 ## Get collaborators Request: GET /api/collaborators Response: ```text [ { "accountId":2, "accountName":"FeodorFitsner", "isOwner":false, "isCollaborator":true, "userId":2018, "fullName":"John Smith", "email":"john@smith.com", "roleId":3040, "roleName":"My Role", "successfulBuildNotification":"all", "failedBuildNotification":"all", "notifyWhenBuildStatusChangedOnly":true, "created":"2014-02-03T20:29:26.6807307+00:00", "updated":"2014-03-07T04:26:09.1051534+00:00" } ] ``` ## Get collaborator Request: GET /api/collaborators/{userId} Response: ```text { "user":{ "accountId":2, "accountName":"FeodorFitsner", "isOwner":false, "isCollaborator":true, "userId":2018, "fullName":"John Smith", "email":"john@smith.com", "roleId":3040, "roleName":"My Role", "successfulBuildNotification":"all", "failedBuildNotification":"all", "notifyWhenBuildStatusChangedOnly":true, "created":"2014-02-03T20:29:26.6807307+00:00", "updated":"2014-03-07T04:26:09.1051534+00:00" }, "roles":[ { "roleId":4, "name":"Administrator", "isSystem":true, "created":"2013-09-26T19:23:39.3615105+00:00" }, { "roleId":5, "name":"User", "isSystem":true, "created":"2013-09-26T19:23:39.3645117+00:00" }, { "roleId":3040, "name":"My Role", "isSystem":false, "created":"2014-03-18T20:12:08.4749886+00:00", "updated":"2014-03-18T20:16:06.8803375+00:00" } ] } ``` ## Add collaborator Request: POST /api/collaborators Request body: ```text { "email":"john@smith.com", "roleId":3040 } ``` Response: 204 ## Update collaborator Request: PUT /api/collaborators Request body: ```text { "userId":2018, "roleId":3040 } ``` Response: 204 ## Delete collaborator Request: DELETE /api/collaborators/{userId} Response: 204 ## Get roles Request: GET /api/roles Response: ```text [ { "roleId":4, "name":"Administrator", "isSystem":true, "created":"2013-09-26T19:23:39.3615105+00:00" }, { "roleId":5, "name":"User", "isSystem":true, "created":"2013-09-26T19:23:39.3645117+00:00" } ] ``` ## Get role Request: GET /api/users/{roleId} Response: ```text { "roleId":3040, "name":"My Role", "isSystem":false, "created":"2014-03-18T20:12:08.4749886+00:00", "groups":[ { "name":"Projects", "permissions":[ { "name":"ManageProjects", "description":"Create, delete projects, update project settings", "allowed":false }, { "name":"UpdateProjectSettings", "description":"Update project settings", "allowed":false }, { "name":"RunProjectBuild", "description":"Run project builds", "allowed":false }, { "name":"DeleteProjectBuilds", "description":"Delete project builds", "allowed":false } ] }, { "name":"Environments", "permissions":[ { "name":"ManageEnvironments", "description":"Create, delete projects, update environment settings", "allowed":false }, { "name":"UpdateEnvironmentSettings", "description":"Update environment settings", "allowed":false }, { "name":"DeployToEnvironment", "description":"Deploy to environment", "allowed":false } ] }, { "name":"Account", "permissions":[ { "name":"UpdateAccountDetails", "description":"Update account details", "allowed":false } ] }, { "name":"Users", "permissions":[ { "name":"AddUser", "description":"Add new user", "allowed":false }, { "name":"UpdateUserDetails", "description":"Update user details", "allowed":false }, { "name":"DeleteUser", "description":"Delete user", "allowed":false } ] }, { "name":"Roles", "permissions":[ { "name":"AddRole", "description":"Add new role", "allowed":false }, { "name":"UpdateRoleDetails", "description":"Update role details", "allowed":false }, { "name":"DeleteRole", "description":"Delete role", "allowed":false } ] }, { "name":"User", "permissions":[ { "name":"ConfigureApiKeys", "description":"Generate API keys", "allowed":false } ] } ] } ``` ## Add role Request: POST /api/roles Request body: ```text { "name":"My Role" } ``` Response: Role details (see [Get role](#get-role)) ## Update role Request: PUT /api/roles Request body: ```text { "roleId":3040, "name":"My Role", "isSystem":false, "created":"2014-03-18T20:12:08.4749886+00:00", "groups":[ { "name":"Projects", "permissions":[ { "name":"ManageProjects", "description":"Create, delete projects, update project settings", "allowed":true }, { "name":"UpdateProjectSettings", "description":"Update project settings", "allowed":true }, { "name":"RunProjectBuild", "description":"Run project builds", "allowed":false }, { "name":"DeleteProjectBuilds", "description":"Delete project builds", "allowed":false } ] }, { "name":"Environments", "permissions":[ { "name":"ManageEnvironments", "description":"Create, delete projects, update environment settings", "allowed":false }, { "name":"UpdateEnvironmentSettings", "description":"Update environment settings", "allowed":false }, { "name":"DeployToEnvironment", "description":"Deploy to environment", "allowed":false } ] }, { "name":"Account", "permissions":[ { "name":"UpdateAccountDetails", "description":"Update account details", "allowed":false } ] }, { "name":"Users", "permissions":[ { "name":"AddUser", "description":"Add new user", "allowed":false }, { "name":"UpdateUserDetails", "description":"Update user details", "allowed":false }, { "name":"DeleteUser", "description":"Delete user", "allowed":false } ] }, { "name":"Roles", "permissions":[ { "name":"AddRole", "description":"Add new role", "allowed":false }, { "name":"UpdateRoleDetails", "description":"Update role details", "allowed":false }, { "name":"DeleteRole", "description":"Delete role", "allowed":false } ] }, { "name":"User", "permissions":[ { "name":"ConfigureApiKeys", "description":"Generate API keys", "allowed":false } ] } ] } ``` Response: Role details (see [Get role](#get-role)) ## Delete role Request: DELETE /api/roles/{roleId} Response: 204 --- ## File: src/docs/byoc/aws.md --- layout: docs title: BYOC - Running builds in AWS cloud --- # Running builds in AWS cloud {:.no_toc} AppVeyor BYOC allows connecting an existing AWS account and running builds in Windows or Linux VMs. * Comment to trigger ToC generation {:toc} ## Overview You can connect your AppVeyor account (on both hosted AppVeyor and on-premise AppVeyor Server) to your own AWS account for AppVeyor to instantiate build VMs in it. It has a lot of benefits like having ability to customize your build image, select desired VM size, set custom build timeout and much more. To simplify setup process for you, we created an automation framework which does all heavy lifting for you: it provisions necessary AWS resources, runs Hashicorp Packer to create a basic build AMI (based on Windows Server 2019), and puts all AppVeyor configuration together. As a result, you should be able to start builds on AWS immediately (and optionally customize your AWS build environment later). > This automation will create AWS resources such as S3 buckets, security group and key pair. Also, Packer will create its own temporary AWS resources and leave AMI for future use by AppVeyor build VMs. Please note that charges for cloud VMs and other cloud resources will be applied directly to your AWS account bill. If AWS account you select contains production resources, you might consider creating a separate account and run the automation against it. Additionally, a separate account is better to differentiate AWS bills for CI machines from other AWS bills. ## Requirements * AWS account ## Assisted setup [TBD] --- ## File: src/docs/byoc/azure.md --- layout: docs title: BYOC - Running builds in Azure cloud --- # Running builds in Azure cloud {:.no_toc} AppVeyor BYOC allows connecting an existing Azure subscription and running builds in Windows or Linux VMs. * Comment to trigger ToC generation {:toc} ## Overview You can connect your AppVeyor account (on both hosted AppVeyor and on-premise AppVeyor Server) to your own Azure subscription for AppVeyor to instantiate build VMs in it. It has a lot of benefits like having ability to customize your build image, select desired VM size, set custom build timeout and much more. To simplify setup process for you, we created an automation framework which does all heavy lifting for you: it provisions necessary Azure resources, runs Hashicorp Packer to create a basic build image (based on Windows Server 2019), and puts all AppVeyor configuration together. As a result, you should be able to start builds on Azure immediately (and optionally customize your Azure build environment later). > This automation will create Azure resources such as storage accounts, containers, virtual networks and subnets in subscription you select. Also, Packer will create its own temporary Azure resources and leave VHD blob for future use by AppVeyor build VMs. Please note that charges for cloud VMs and other cloud resources will be applied directly to your Azure subscription bill. If the subscription you select contains production resources, you might consider creating a separate subscription and run the automation against it. Additionally, a separate subscription is better to differentiate Azure bills for CI machines from other Azure bills. ## Requirements * Azure subscription with "Contributor" access ## Assisted setup [TBD] --- ## File: src/docs/byoc/docker.md --- layout: docs title: BYOC - Running builds in Docker containers --- # Running builds in Docker containers {:.no_toc} AppVeyor BYOC allows connecting an existing computer with Docker (your workstation, cloud VM or the server in your LAN) and running builds in containers. * Comment to trigger ToC generation {:toc} ## Requirements * Supported Docker host operating systems: * Windows 10 Version 1803 and later * Windows Server 2019 and later * Ubuntu 18.04 * macOS 10.13 “High Sierra” and later * Supported container operating systems: * Windows Server Core and Windows Nano Server (Windows hosts only) * Linux (Windows, Linux and macOS hosts) * Docker installed and configured. `docker` tool available in PATH. * Supported Docker editions: * Docker Desktop for Windows (Docker CE) * Docker Engine Enterprise (Docker EE) on Windows Server * Docker CE on Linux * Docker Desktop for Mac ## Assisted setup Following cloud configuration wizard is the fastest and the easiest way to configure Docker computer to run your builds. At the end of the wizard you'll be given a few commands that you run on the target computer to get it up and running in AppVeyor. In AppVeyor web portal: * Select **Self-hosted jobs** in the top menu; * Click **Add cloud** to start "Add your own cloud" wizard; * Choose **Docker** and then operating system running on Docker host * Select containers **Base image** to configure and click **Next**; * Follow the instructions. `Connect-AppVeyorToDocker` cmdlet ([source](https://github.com/appveyor/build-images/blob/master/Connect-AppVeyorToDocker.ps1)) will configure a new cloud, install AppVeyor Host Agent on the computer and connect it to the cloud. * Click **Finish** to return to **BYOC** page and make sure the status of created cloud is **Active** meaning Host Agent was able to connect to AppVeyor. * [Update project settings to run builds on your computer](/docs/byoc/#routing-builds-to-your-cloud). --- ## File: src/docs/byoc/gce.md --- layout: docs title: BYOC - Running builds in GCE cloud --- # Running builds in GCE cloud {:.no_toc} AppVeyor BYOC allows connecting your GCE cloud project and running builds in Windows or Linux VMs. * Comment to trigger ToC generation {:toc} ## Overview You can connect your AppVeyor account (on both hosted AppVeyor and on-premise AppVeyor Server) to your own Google cloud account and project for AppVeyor to instantiate build VMs in it. It has a lot of benefits like having ability to customize your build image, select desired VM size, set custom build timeout and much more. To simplify setup process for you, we created an automation framework which does all heavy lifting for you: it provisions necessary Google Cloud Engine and Storage resources, runs Hashicorp Packer to create a basic build image (based on Windows Server 2019), and puts all AppVeyor configuration together. As a result, you should be able to start builds on Google Cloud Engine (GCE) immediately (and optionally customize your GCE build environment later). > This automation will create Google resources such as network and service account, as well as GCS buckets. Also, Packer will create its own temporary GCE resources and leave VM image for future use by AppVeyor build VMs. Please note that charges for cloud VMs and other cloud resources will be applied directly to your GCE account bill. If GCE project you select contains production resources, you might consider creating a separate project or even account and run the automation against it. Additionally, a separate account is better to differentiate Google bills for CI machines from other Google bills ## Requirements * Google Compute Platform (GCP) account ## Assisted setup [TBD] --- ## File: src/docs/byoc/hyper-v.md --- layout: docs title: BYOC - Running builds in Hyper-V VMs --- # Running builds in Hyper-V virtual machines {:.no_toc} AppVeyor BYOC allows connecting an existing server with Hyper-V (your Windows 10 workstation, cloud VM or the server in your LAN) and running builds in Windows or Linux VMs. * Comment to trigger ToC generation {:toc} ## Requirements * Supported **Hyper-V host** operating systems: * Windows 10 Version 1803 and later * Windows Server 2016 and later * Azure [Dsv3-series](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/sizes-general#dsv3-series-1) VMs with nested virtualization enabled * Supported **guest** operating systems: * Windows Server 2019 * Windows Server 2016 * Ubuntu 18.04 * Hyper-V feature enabled on the host ## Assisted setup Following cloud configuration wizard is the fastest and the easiest way to configure Docker computer to run your builds. At the end of the wizard you'll be given a few commands that you run on the Hyper-V host to get it up and running in AppVeyor. In AppVeyor web portal: * Select **Self-hosted jobs** in the top menu; * Click **Add cloud** to start "Add your own cloud" wizard; * Choose **Hyper-V**; * Select **Base image** to configure image builder and click **Next**; * Follow the instructions. `Connect-AppVeyorToHyperV` cmdlet ([source](https://github.com/appveyor/build-images/blob/master/Connect-AppVeyorToHyperV.ps1)) will build master image (.vhdx), configure a new cloud, install AppVeyor Host Agent on the computer and connect it to the cloud. * Click **Finish** to return to **BYOC** page and make sure the status of created cloud is **Active** meaning Host Agent was able to connect to AppVeyor. * [Update project settings to run builds on your computer](/docs/byoc/#routing-builds-to-your-cloud). --- ## File: src/docs/byoc/index.md --- layout: docs title: Bring Your Own Cloud or Computer (BYOC) --- # Bring Your Own Cloud or Computer (BYOC) {:.no_toc} * Comment to trigger ToC generation {:toc} ## What is BYOC Bring Your Own Cloud (BYOC) allows running builds on your own infrastructure. Builds could be run inside VMs (Azure, AWS, GCE, Hyper-V), in Docker containers (Windows, Linux and macOS) or directly on the host (Windows, Linux and macOS). BYOC is available for hosted AppVeyor accounts and self-hosted AppVeyor Server installations. Some of the reasons you may want to run builds on your infrastructure: * Using under-utilized existing hardware such as an old build server under your desk; * Using hardware with better performance like your team's workstations or VMs with better/different characteristics (GPU-enabled, memory-, disk-, network-optimized); * Running builds on your team's Macs or a Mac hosted on Macstadium. While we are hard-working on bringing macOS support to AppVeyor service this might be a viable option for now; * Custom/proprietary software that cannot be installed during the build; * Security/compliance requirements like the code or build artifacts not leaving particular cloud/region/zone/network; ## How is it better than "self-hosted agents" in other CI/CD solutions? AppVeyor really shines at running builds on dynamically provisioned VMs. While AppVeyor also supports running builds on a host directly (aka "self-hosted agent") creating VMs on demand has a number of advantages: * **Significant savings on a monthly cloud bill**. Build VM is created for the duration of a build job and immediately deleted when this build is over. Major cloud providers have per-minute pricing and as a result you pay only for the "clean" build time. With a "self-hosted agent" approach a VM with an agent is running 24x7 waiting for your builds, consuming electricity or adding to your monthly bill. You are not going to run expensive GPU-enabled instance for 24x7x365, aren't you? * **Pristine environment on every build**. Build VMs are provisioned from an image or snapshot and never reused for the consequent builds. You get clean and predictable environment every time you run a new build. With "self-hosted agent" approach concurrent builds are running directly on the host operating system, so they interfere, produce leftovers (files, databases, configs, registry settings) or could completely kill the host machine. It makes you think about additional guard/synchronizing/cleanup code in your builds thus wasting your time. * **Multiple parallelism**. A single build can be run on hundreds of VMs simultaneously for a shorter period of time. Say, you have a suite with 1,000 tests and it takes 1 hour on a single core to run them all. You can run the suite on 10 single-core VMs in parallel and reduce the overall test time to 6 minutes by paying the same amount to the cloud provider! ## What about build VM images? One of the benefits of hosted AppVeyor service is that you get build VM with a tons of pre-installed software, curated and regularly updated by AppVeyor team. The greatest fear of running builds on your own VMs is a necessity of maintaining build VM images (the template is used to create a VM). You've been heard! BYOC is not just a feature, but it is a framework and significant part of this framework is the code helping you to create customized build VM images for all platforms and clouds we support: Azure, AWS, GCP, Hyper-V and Docker - thanks to [Packer by HashiCorp](https://www.packer.io/). All scripts and Packer templates used by BYOC framework are [open-source](https://github.com/appveyor/build-images). ## Getting started To configure your own build environment select **Self-hosted jobs** in the top menu and click **Add cloud**. We created a wizard that will guide you through the process and give you commands based on your selection that should be run on your computer: Commands are PowerShell cmdlets that are part of [AppVeyorBYOC](https://www.powershellgallery.com/packages/AppVeyorBYOC) module. PowerShell is the universal shell/language that can be installed on [Windows](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-core-on-windows?view=powershell-6), [Linux](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-core-on-linux?view=powershell-6) and [macOS](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-core-on-macos?view=powershell-6). Below you can find additional notes as well as alternative manual instructions for each of the clouds/platforms supported by BYOC: | Cloud/Platform | Builds run in | | --- | --- | | [**Windows**](/docs/byoc/windows/) | Windows host directly | | [**Linux**](/docs/byoc/linux/) | Linux host directly | | [**macOS**](/docs/byoc/mac/) | macOS host directly | | [**Docker**](/docs/byoc/docker/) | Windows or Linux containers on Windows, Linux or macOS | | [**Azure**](/docs/byoc/azure/) | Windows or Linux VMs provisioned in Azure cloud | | [**AWS**](/docs/byoc/aws/) | Windows or Linux VMs provisioned in AWS cloud | | [**GCE**](/docs/byoc/gce/) | Windows or Linux VMs provisioned in GCE cloud | | [**Hyper-V**](/docs/byoc/hyper-v/) | Windows or Linux VMs provisioned on Hyper-V host | ## Routing builds to your cloud To run builds in your own cloud/computer you should update project settings. If you are configuring AppVeyor project via **UI settings** (no `appveyor.yml` in the repository) open project settings and then click **Environment** tab: * `Build cloud` - select your private build cloud name; * `Build worker image` - select your build worker image; * Save project settings. If you are configuring AppVeyor project via **appveyor.yml** then UI settings for build cloud and image are ignored. Specify build cloud and image in `appveyor.yml` instead: ```yaml build_cloud: image: ``` Alternatively, you can configure build cloud and image via **environment variables** (defined either on UI or in `appveyor.yml`). * `APPVEYOR_BUILD_WORKER_CLOUD` - the name of your build cloud * `APPVEYOR_BUILD_WORKER_IMAGE` - the name of your build worker image > NOTE: Build clouds and images configured via environment variables override both UI and `appveyor.yml` settings. This could be useful for quick cloud testing or multi-job builds. ## Build clusters [TBD] - grouping multiple clouds, failover, etc.