kotlin-dsl/CommitStatusPublisher.xml

<?xml version="1.0" encoding="UTF-8"?>


<dsl-extension kind="buildFeature" type="commit-status-publisher" generateDslJar="true">
  <class name="CommitStatusPublisher">
    <description>
      A [build feature](https://www.jetbrains.com/help/teamcity/?Commit+Status+Publisher) publishing
      status to external system
    </description>
  </class>
  <function name="commitStatusPublisher">
    <description>
      Enables [status publishing](https://www.jetbrains.com/help/teamcity/?Commit+Status+Publisher) to external system
      @see CommitStatusPublisher
    </description>
  </function>
  <params>
    <param name="vcsRootId" dslName="vcsRootExtId" ref="VCS_ROOT">
      <description>
        Id of the VCS root for which commits a status should be published.
        Set to an empty string to publish status for all VCS roots attached to a build configuration.
      </description>
    </param>
    <param name="publisherId" dslName="publisher" type="compound" mandatory="true">
      <description>
        Specifies to which system a status should be published
      </description>
      <option name="bitbucketCloud" value="bitbucketCloudPublisher">
        <description>
          Publish status to Bitbucket Cloud
        </description>
        <param name="bitbucketUsername" dslName="userName" deprecated="true">
          <description>
            A username for Bitbucket Cloud connection
          </description>
          <deprecated>
            Use authType property instead
          </deprecated>
        </param>
        <param name="secure:bitbucketPassword" dslName="password" deprecated="true">
          <description>
            A password for Bitbucket Cloud connection
          </description>
          <deprecated>
            Use authType property instead
          </deprecated>
        </param>
        <param name="authType" type="compound">
          <description>
            Use username / password credentials
          </description>
          <option name="password" value="password">
            <param name="bitbucketUsername" dslName="userName" mandatory="true">
              <description>
                A username for Bitbucket Cloud connection
              </description>
            </param>
            <param name="secure:bitbucketPassword" dslName="password" mandatory="true">
              <description>
                A password for Bitbucket Cloud connection
              </description>
            </param>
          </option>
          <option name="storedToken" value="storedToken">
            <description>
              Use token credentials stored in TeamCity
            </description>
            <param name="tokenId" mandatory="true">
              <description>
                The internal ID of the token to use for the connection
              </description>
            </param>
          </option>
          <option name="vcsRoot" value="vcsRoot">
            <description>
              Use VCS root credentials
            </description>
          </option>
        </param>
      </option>
      <option name="bitbucketServer" value="atlassianStashPublisher">
        <description>
          Publish status to Bitbucket Server / Data Center
        </description>
        <param name="stashBaseUrl" dslName="url">
          <description>
            Bitbucket Server URL
          </description>
        </param>
        <param name="stashUsername" dslName="userName">
          <description>
            A username for Bitbucket Server / Data Center connection
          </description>
          <deprecated>
            Use authType property instead
          </deprecated>
        </param>
        <param name="secure:stashPassword" dslName="password">
          <description>
            A password for Bitbucket Server / Data Center connection
          </description>
          <deprecated>
            Use authType property instead
          </deprecated>
        </param>
        <param name="authType" type="compound">
          <option name="password" value="password">
            <description>
              Use username / password credentials
            </description>
            <param name="stashUsername" dslName="userName" mandatory="true">
              <description>
                A username for Bitbucket Server / Data Center connection
              </description>
            </param>
            <param name="secure:stashPassword" dslName="password" mandatory="true">
              <description>
                A password for Bitbucket Server / Data Center connection
              </description>
            </param>
          </option>
          <option name="storedToken" value="storedToken">
            <description>
              Use token credentials stored in TeamCity
            </description>
            <param name="tokenId" mandatory="true">
              <description>
                The internal ID of the token to use for the connection
              </description>
            </param>
          </option>
          <option name="vcsRoot" value="vcsRoot">
            <description>
              Use VCS root credentials
            </description>
          </option>
        </param>
      </option>
      <option name="gerrit" value="gerritStatusPublisher">
        <description>
          Publish status to Gerrit Code Review
        </description>
        <param name="gerritServer" dslName="server" mandatory="true">
          <description>
            Gerrit server in the format: {server}[:{port}]
          </description>
        </param>
        <param name="gerritProject" dslName="gerritProject" mandatory="true">
          <description>
            Gerrit project name
          </description>
        </param>
        <param name="label">
          <description>
            Gerrit label to be used, "Verified" is used if the parameter is left blank
          </description>
        </param>
        <param name="failureVote" mandatory="true">
          <description>
            A failed build vote, e.g. "-1"
          </description>
        </param>
        <param name="successVote" mandatory="true">
          <description>
            A successful build vote, e.g. "+1"
          </description>
        </param>
        <param name="gerritUsername" dslName="userName" mandatory="true">
          <description>
            A username for Gerrit connection
          </description>
        </param>
        <param name="teamcitySshKey" dslName="uploadedKey">
          <description>
            Name of the [uploaded key](https://www.jetbrains.com/help/teamcity/?SSH+Keys+Management) to use for Gerrit connection
          </description>
        </param>
      </option>
      <option name="github" value="githubStatusPublisher">
        <description>
          Publish status to GitHub
        </description>
        <param name="github_host" dslName="githubUrl" mandatory="true">
          <description>
            GitHub server URL.
            Use "https://api.github.com" for projects hosted at github.com. For GitHub enterprise use the URL in the
            following format: http{s}://{host}:{port}/api/v3
          </description>
        </param>
        <param name="github_authentication_type" dslName="authType" type="compound">
          <description>
            Type of authentication
          </description>
          <option name="personalToken" value="token">
            <description>
              Authentication using personal token
            </description>
            <param name="secure:github_access_token" dslName="token" mandatory="true">
              <description>
                Personal token to use
              </description>
            </param>
          </option>
          <option name="password" value="password">
            <description>
              Password authentication
            </description>
            <param name="github_username" dslName="userName" mandatory="true">
              <description>
                A username for GitHub connection
              </description>
            </param>
            <param name="secure:github_password" dslName="password" mandatory="true">
              <description>
                A password for GitHub connection
              </description>
            </param>
          </option>
          <option name="vcsRoot" value="vcsRoot">
            <description>
              Use VCS root credentials
            </description>
          </option>
          <option name="storedToken" value="storedToken">
            <description>
              Use GitHub App credentials
            </description>
            <param name="tokenId" dslName="tokenId" mandatory="true">
              <description>
                Internal ID of a token in TeamCity token storage
              </description>
            </param>
          </option>
        </param>
      </option>
      <option name="gitlab" value="gitlabStatusPublisher">
        <description>
          Publish status to GitLab
        </description>
        <param name="gitlabApiUrl">
          <description>
            GitLab URL in the format http[s]://{hostname}[:port]/api/v4. If unspecified, the URL will be composed based on the VCS root fetch URL.
          </description>
        </param>
        <param name="secure:gitlabAccessToken" dslName="accessToken" deprecated="true">
          <description>
            Access token to use for GitLab connection. Can be found at /profile/account in GitLab.
          </description>
          <deprecated>
            Use authType property instead
          </deprecated>
        </param>
        <param name="authType" dslName="authType" type="compound">
          <option name="personalToken" value="token">
            <description>
              Authentication using personal token
            </description>
            <param name="secure:gitlabAccessToken" dslName="accessToken" mandatory="true">
              <description>
                Access token to use for GitLab connection. Can be found at /profile/account in GitLab.
              </description>
            </param>
          </option>
          <option name="storedToken" value="storedToken">
            <description>
              Use GitLab OAuth credentials
            </description>
            <param name="tokenId" dslName="tokenId" mandatory="true">
              <description>
                Internal ID of a token in TeamCity token storage
              </description>
            </param>
          </option>
          <option name="vcsRoot" value="vcsRoot">
            <description>
              Use VCS root credentials
            </description>
          </option>
        </param>
      </option>
      <option name="upsource" value="upsourcePublisher">
        <description>
          Publish status to Upsource
        </description>
        <param name="upsourceServerUrl" dslName="serverUrl" mandatory="true">
          <description>
            Upsource server URL
          </description>
        </param>
        <param name="upsourceProjectId" dslName="projectId" mandatory="true">
          <description>
            Upsource project ID
          </description>
        </param>
        <param name="upsourceUsername" dslName="userName" mandatory="true">
          <description>
            A username for Upsource connection
          </description>
        </param>
        <param name="secure:upsourcePassword" dslName="password" mandatory="true">
          <description>
            A password for Upsource connection
          </description>
        </param>
      </option>
      <option name="azureDevOps" value="tfs">
        <description>
          Publish build status to Azure DevOps / TFS
        </description>
        <param name="tfsServerUrl" dslName="serverUrl">
          <description>
            Azure DevOps / TFS Server URL
          </description>
        </param>
        <param name="tfsAuthType" dslName="authType" type="compound">
          <description>
            Authentication type
          </description>
          <option name="personalToken" value="token">
            <description>
              Authentication using personal token
            </description>
            <param name="secure:accessToken" dslName="accessToken" mandatory="true">
              <description>
                A Personal Access Token value
              </description>
            </param>
          </option>
          <option name="storedToken" value="storedToken">
            <description>
              Use token credentials stored in TeamCity
            </description>
            <param name="tokenId" mandatory="true">
              <description>
                The internal ID of the token to use for the connection
              </description>
            </param>
          </option>
        </param>
        <param name="publish.pull.requests" dslName="publishPullRequests" type="boolean" trueValue="true" falseValue="">
          <description>
            Enables publishing build status for pull requests
          </description>
        </param>
      </option>
      <option name="tfs" value="tfs">
        <deprecated>
          Use 'azureDevOps' option instead
        </deprecated>
        <description>
          Publish build status to Azure DevOps / TFS
        </description>
        <param name="tfsServerUrl" dslName="serverUrl">
          <description>
            Azure DevOps / TFS Server URL
          </description>
        </param>
        <param name="tfsAuthType" dslName="authType" mandatory="true">
          <description>
            Authentication type
          </description>
        </param>
        <param name="secure:accessToken" dslName="accessToken" mandatory="true">
          <description>
            A Personal Access Token value
          </description>
        </param>
        <param name="publish.pull.requests" dslName="publishPullRequests" type="boolean" trueValue="true" falseValue="">
          <description>
            Enables publishing build status for pull requests
          </description>
        </param>
      </option>
      <option name="space" value="spaceStatusPublisher">
        <description>
          Publish status to JetBrains Space
        </description>
        <param name="spaceCredentialsType" dslName="authType" type="compound">
          <description>
            Type of authentication
          </description>
          <option name="connection" value="spaceCredentialsConnection">
            <description>
              Authentication using JetBrains Space Connection
            </description>
            <param name="spaceConnectionId" dslName="connectionId" mandatory="true">
              <description>
                JetBrains Space Connection project feature ID
              </description>
            </param>
          </option>
        </param>
        <param name="spaceProjectKey" dslName="projectKey">
          <description>
            JetBrains Space Project Key
          </description>
        </param>
        <param name="spaceCommitStatusPublisherDisplayName" dslName="displayName">
          <description>
            Display name
          </description>
        </param>
      </option>
      <option name="swarm" value="perforceSwarmPublisher">
        <description>
          Publish build status to Perforce P4 Code Review (Helix Swarm)
        </description>
        <param name="swarmUrl" dslName="serverUrl" mandatory="true">
          <description>
            Peforce P4 Code Review (Helix Swarm) Server URL
          </description>
        </param>
        <param name="swarmUser" dslName="username" mandatory="true">
          <description>
            Username to access the server.
          </description>
        </param>
        <param name="secure:swarmPassword" dslName="token" mandatory="true">
          <description>
            Token or password to access the Perforce P4 Code Review (Helix Swarm) server.
          </description>
        </param>
        <param name="createSwarmTest" dslName="createSwarmTest" type="boolean">
          <description>
            If set, TeamCity will create a test run on the P4 Code Review (Helix Swarm) server and update its status according to
            the build status in TeamCity.
          </description>
        </param>
        <param name="commentOnEvents" type="boolean">
          <description>
            If enabled, TeamCity will add comments to a related review when a build fails or finishes successfully. This defaults to &lt;code&gt;true&lt;/code&gt;.
          </description>
        </param>
      </option>

    </param>
  </params>
  <examples>
    <example>
      <description>
        Enables publishing build statuses to commits in JetBrains Space.
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
          publisher = space {
            authType = connection {
              connectionId = "&lt;JetBrains Space connection id>"
            }
            displayName = "&lt;Display name>" // optional, "TeamCity" by default
          }
        }
      </code>
    </example>
    <example>
      <description>
        Enables publishing build statuses to commits in GitHub.com / GitHub Enterprise.
        It is not recommended to store secure values directly in the DSL code,
        see [Managing Tokens](https://www.jetbrains.com/help/teamcity/storing-project-settings-in-version-control.html#Managing+Tokens)
        section of our documentation.
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
          publisher = github {
            githubUrl = "&lt;GitHub URL, https://api.github.com for github.com>"
            authType = personalToken { // authType = password { ... } to use username and password
              token = "credentialsJSON:*****"
            }
          }
        }
      </code>
    </example>
    <example>
      <description>
        Enables publishing build statuses to commits in GitHub.com / GitHub Enterprise.
        Uses the credentials of the VCS root.
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
          publisher = github {
            githubUrl = "&lt;GitHub URL, https://api.github.com for github.com>"
            authType = vcsRoot()
          }
        }
      </code>
    </example>
    <example>
      <description>
        Enables publishing build statuses to commits in GitHub.com / GitHub Enterprise.
        Uses a GitHub App installation token stored in TeamCity.
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // A VCS root must be specified to use this authentication type
          publisher = github {
            githubUrl = "&lt;GitHub URL, https://api.github.com for github.com>"
            authType = storedToken {
              tokenId = "tc_token_id:*****"
            }
          }
        }
      </code>
    </example>
    <example>
      <description>
        Enables publishing build statuses to commits in GitLab.com / GitLab CE/EE.
        It is not recommended to store secure values directly in the DSL code,
        see [Managing Tokens](https://www.jetbrains.com/help/teamcity/storing-project-settings-in-version-control.html#Managing+Tokens)
        section of our documentation.
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
          publisher = gitlab {
            gitlabApiUrl = "https://&lt;GitLab URL>/api/v4" // optional, the URL will be composed based on the VCS root fetch URL if omitted (https://gitlab.com/api/v4 for gitlab.com)
            accessToken = personalToken { // authType = vcsRoot() to take credentials from the VCS root
              accessToken = "credentialsJSON:*****"
            }
          }
        }
      </code>
    </example>
    <example>
      <description>
        Enables publishing build statuses to commits in GitLab.com / GitLab CE/EE.
        Instead of personal token authentication a refreshable access token stored in TeamCity is used.
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
          publisher = gitlab {
            gitlabApiUrl = "https://&lt;GitLab URL>/api/v4" // optional, the URL will be composed based on the VCS root fetch URL if omitted (https://gitlab.com/api/v4 for gitlab.com)
            authType = storedToken {
              tokenId = "tc_token_id:*****"
            }
          }
        }
      </code>
    </example>
    <example>
      <description>
        Enables publishing build statuses to commits in Bitbucket Cloud.
        The password must be Bitbucket App password generated by user.
        It is not recommended to store secure values directly in the DSL code,
        see [Managing Tokens](https://www.jetbrains.com/help/teamcity/storing-project-settings-in-version-control.html#Managing+Tokens)
        section of our documentation.
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
          publisher = bitbucketCloud {
            authType = password { // authType = vcsRoot() to take credentials from the VCS root
              userName = "&lt;username>"
              password = "credentialsJSON:*****"
            }
          }
        }
      </code>
    </example>
    <example>
      <description>
        Enables publishing build statuses to commits in Bitbucket Cloud.
        Instead of password authentication an access token stored in TeamCity is used.
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
          publisher = bitbucketCloud {
            authType = storedToken {
              tokenId = "tc_token_id:*****"
            }
          }
        }
      </code>
    </example>
    <example>
      <description>
        Enables publishing build statuses to commits in Bitbucket Server / Data Center.
        The password can be either user's password (not recommended) or Bitbucket HTTP access token generated by user.
        It is not recommended to store secure values directly in the DSL code,
        see [Managing Tokens](https://www.jetbrains.com/help/teamcity/storing-project-settings-in-version-control.html#Managing+Tokens)
        section of our documentation.
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
          publisher = bitbucketServer {
              url = "&lt;Bitbucket Server Base URL>" // optional, the URL will be composed based on the VCS root fetch URL if omitted
              authType = password { // authType = vcsRoot() to take credentials from the VCS root
                userName = "&lt;username>"
                password = "credentialsJSON:*****"
              }
          }
        }
      </code>
    </example>
    <example>
      <description>
        Enables publishing build statuses to commits in Bitbucket Server / Data Center.
        Instead of password authentication an access token stored in TeamCity is used.
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
          publisher = bitbucketServer {
            url = "&lt;Bitbucket Server Base URL>"
            authType = storedToken {
              tokenId = "tc_token_id:*****"
            }
          }
        }
      </code>
    </example>
    <example>
      <description>
        Enables publishing build statuses to commits in Azure DevOps
        For now only personal access token authentication type is supported. It is not recommended to store secure values directly in the DSL code,
        see [Managing Tokens](https://www.jetbrains.com/help/teamcity/storing-project-settings-in-version-control.html#Managing+Tokens)
        section of our documentation.
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
          publisher = azureDevOps {
            serverUrl = "&lt;Azure DevOps URL>" // optional
            authType = personalToken {
              accessToken = "tc_token_id:*****"
            }
            publishPullRequests = true // optional
          }
        }
      </code>
    </example>
    <example>
      <description>
        Enables publishing build statuses to commits in Azure DevOps
        Instead of password authentication an access token stored in TeamCity is used.
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
          publisher = azureDevOps {
            serverUrl = "&lt;Azure DevOps URL>" // optional
            authType = storedToken {
              tokenId = "tc_token_id:*****"
            }
            publishPullRequests = true // optional
          }
        }
      </code>
    </example>
    <example>
      <description>
        Enables publishing build statuses to Perforce P4 Code Review (Helix Swarm).
        For now only personal access token authentication type is supported. It is not recommended to store secure values directly in the DSL code,
        see [Managing Tokens](https://www.jetbrains.com/help/teamcity/storing-project-settings-in-version-control.html#Managing+Tokens)
        section of our documentation.
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
          publisher = swarm {
            serverUrl = "&lt;Swarm URL>"
            username = "&lt;username>"
            token = "credentialsJSON:*****"
            createSwarmTest = true // optional, if set, TeamCity will create a test run on the P4 Code Review (Helix Swarm) server and update its status according to the build status in TeamCity.
            commentOnEvents = true // optional
          }
        }
      </code>
    </example>
    <example>
      <description>
        Enables voting in Gerrit based on build statuses
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
          publisher = gerrit {
            server = "&lt;Gerrit server URL>"
            gerritProject = "&lt;Gerrit project name>"
            label = "&lt;label>" // e.g. Verified
            failureVote = "&lt;failed build vote>" // e.g. -1
            successVote = "&lt;successful build vote>" // e.g. +1
            userName = "&lt;username>"
            uploadedKey = "&lt;SSH key name>"
          }
        }
      </code>
    </example>
    <example>
      <description>
        Enables publishing build statuses to JetBrains Upsource.
        It is not recommended to store secure values directly in the DSL code,
        see [Managing Tokens](https://www.jetbrains.com/help/teamcity/storing-project-settings-in-version-control.html#Managing+Tokens)
        section of our documentation.
      </description>
      <code>
        commitStatusPublisher {
          vcsRootExtId = "${&lt;VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
          publisher = upsource {
            serverUrl = "&lt;Upsource URL>"
            projectId = "&lt;Upsource project id>"
            userName = "&lt;username>"
            password = "credentialsJSON:*****"
          }
        }
      </code>
    </example>
  </examples>
</dsl-extension>