Interface SBuildType

    • Method Detail

      • getHistory

        java.util.List<SFinishedBuild> getHistory​(@Nullable
                                                  User user,
                                                  boolean includeCanceled,
                                                  boolean orderByChanges)
        Returns all finished builds, visible for the specified user of this configuration.
        Parameters:
        user - specified user. If user is null no personal builds will be included into the list, otherwise there will be personal builds for the specified user.
        includeCanceled - if canceled builds should be included.
        orderByChanges - if true, builds are ordered by changes, i.e. most recent build with recent changes goes first; if false, most recent builds go first, regardless change order
        Returns:
        list of all finished builds sorted according to orderByChanges field.
      • getLastChangesStartedBuild

        @Nullable
        SBuild getLastChangesStartedBuild()
        Returns instance of the build, finished or running, which contains latest changes in this build configuration
        Returns:
        build with latest changes
      • getAgentCompatibilities

        java.util.List<AgentCompatibility> getAgentCompatibilities()
        Returns information about what agent are compatible with the configuration, what are incompatible and why. AgentCompatibility are provided for all authorized agents.
        Returns:
        list of compatibility information holders.
      • getAgentCompatibility

        <T extends SBuildAgentAgentCompatibility getAgentCompatibility​(@NotNull
                                                                         T agent)
        Returns information about agent compatibility for the specified agent.
        Parameters:
        agent - the given agent.
        Returns:
        agent compatibility for the specified agent.
      • getCanRunAgents

        <T extends BuildAgent> java.util.List<T> getCanRunAgents()
        Returns list of agents where this build configuration can run. Build configuration can run on an agent if this agent is authorized and if agent run policy BuildAgentManager.RunConfigurationPolicy allows to run this build configuration. Note that this method does not consider agent pool associations.
        Returns:
        list of agents where this build configuration can run sorted by agent name
      • getCanRunAndCompatibleAgents

        <T extends BuildAgent> java.util.List<T> getCanRunAndCompatibleAgents​(boolean includeDisabled)
        Returns list of agents which are both allowed to run this configuration and are compatible with it.
        Parameters:
        includeDisabled - true to include disabled agents in the list, by default they are excluded
        Returns:
        list of agents which are both allowed to run this configuration and are compatible with it.
      • getBuildNumbers

        BuildNumbers getBuildNumbers()
        Returns interface to manipulate current build counter
        Returns:
        see above
      • getRunningBuilds

        @NotNull
        java.util.List<SRunningBuild> getRunningBuilds()
        Same as getRunningBuilds(null)
        Specified by:
        getRunningBuilds in interface BuildType
        Returns:
        list of running builds
      • getLastChangesFinished

        @Nullable
        SFinishedBuild getLastChangesFinished()
        Description copied from interface: BuildType
        Returns last finished instance for the build configuration with last user changes (personal builds and canceled builds are excluded).
        Specified by:
        getLastChangesFinished in interface BuildType
        Returns:
        last finished build (ordered by changes) from the default branch.
      • getLastChangesSuccessfullyFinished

        @Nullable
        SFinishedBuild getLastChangesSuccessfullyFinished()
        Description copied from interface: BuildType
        Returns last successfully finished build in the configuration with last user changes, personal builds are not considered
        Specified by:
        getLastChangesSuccessfullyFinished in interface BuildType
        Returns:
        last successfully finished build (ordered by changes) from the default branch.
      • setPaused

        void setPaused​(boolean paused,
                       @Nullable
                       User user,
                       java.lang.String comment)
                throws ReadOnlyEntityException
        Pause/unpause this build configuration. Paused build configuration is not triggered by VCS check-ins and time triggers.
        Parameters:
        paused - if configuration should be paused
        user - use who is pausing the configuration
        comment - user comment
        Throws:
        ReadOnlyEntityException
        Since:
        4.5, 9.0.2 this method no longer persists build configuration on disk, you should call persist() method
      • getPauseComment

        @Nullable
        Comment getPauseComment()
        Returns comment for pausing/resuming this build type
        Returns:
        comment for pausing/resuming this build type
        Since:
        4.5
      • setDescription

        void setDescription​(@Nullable
                            java.lang.String description)
                     throws ReadOnlyEntityException
        Changes configuration description.
        Parameters:
        description - new configuration description.
        Throws:
        ReadOnlyEntityException
      • getArtifactsReferences

        java.util.List<SBuildType> getArtifactsReferences()
        Returns list of build configurations which depend on this build configurations artifacts
        Returns:
        list of build configurations
      • getNumberOfArtifactReferences

        int getNumberOfArtifactReferences()
        Returns number of dependent build configuration having references to this build configuration. This number may be greater than the size of the list getArtifactsReferences() because it takes into account all dependent build configurations while getArtifactsReferences() returns only build configurations accessible to an authority currently set in the security context.
        Returns:
        see above
      • getArtifactsDirectory

        @NotNull
        java.io.File getArtifactsDirectory()
        Returns directory containing artifacts of this build configuration.
        Returns:
        artifacts directory on the server.
      • getPendingChanges

        java.util.List<SVcsModification> getPendingChanges()
        Returns changes in this build configuration already detected but not associated with a build. Only own changes are returned ignoring changes from dependencies option.
        Specified by:
        getPendingChanges in interface BuildType
        Returns:
        list of version control modifications, which are detected but no build with these modifications is created yet.
      • getPendingChangesCommitters

        java.util.Collection<SUser> getPendingChangesCommitters()
        Returns pending changes committers to this build configuration
        Returns:
        see above
        Since:
        4.5
      • getModificationsSinceLastSuccessful

        java.util.List<SVcsModification> getModificationsSinceLastSuccessful()
        Returns all modifications made since last successfully finished build
        Specified by:
        getModificationsSinceLastSuccessful in interface BuildType
        Returns:
        list of version control modifications, detected since last successful finished build has been finished
      • getVcsSettingsHash

        @Deprecated
        @NotNull
        java.lang.String getVcsSettingsHash​(@NotNull
                                            java.util.List<VcsRootInstanceEntry> vcsRootEntries)
        Deprecated.
        since 10.0
        Return name of the directory which should be used as checkout directory for this build configuration if explicit checkout directory is not specified. In fact, this name is a generated hash which depends on VCS Roots associated with this build configuration and some other settings, such as CheckoutType BuildTypeDescriptor.getCheckoutType() and checkout rules BuildTypeSettings.getCheckoutRules(jetbrains.buildServer.vcs.VcsRoot) Deprecated since 10.0, because for auto checkout mode this hash depends on effective checkout mode and is calculated on the agent. As a workaround, for auto checkout this method returns hash as if agent checkout is used.
        Parameters:
        vcsRootEntries - vcs roots with checkout rules to get name hash for.
        Returns:
        name of the directory which will be used as last part of checkout directory
        See Also:
        BuildTypeSettings.setCheckoutDirectory(String)
      • getVcsSettingsHash

        @NotNull
        @Deprecated
        java.lang.String getVcsSettingsHash()
        Deprecated.
        since 10.0
        Returns build configuration vcs settings hash.
        Note: be careful, when using this value for running build. Build type might already be updated Deprecated since 10.0, because for auto checkout mode this hash depends on effective checkout mode and is calculated on the agent. As a workaround, for auto checkout this method returns hash as if agent checkout is used.
        Returns:
        see above
        Since:
        5.0
      • getVcsRootsHash

        @NotNull
        @Deprecated
        java.lang.String getVcsRootsHash()
        Deprecated.
        since 10.0
        Returns build configuration vcs roots hash without taking checkout directory into account
        The resulting hash is an equal to the default checkout directory (since 10.0 it is true only for not auto checkout type). Note: be careful, when using this value for running build. Build type might already be updated Deprecated since 10.0, because for auto checkout mode this hash depends on effective checkout mode and is calculated on the agent. As a workaround, for auto checkout this method returns hash as if agent checkout is used.
        Returns:
        see above
        Since:
        9.1
      • releaseSources

        void releaseSources()
        Releases sources of the build configuration on ALL agents where this configuration built. After that full checkout will be performed when build of this configuration starts on such agents.
      • releaseSources

        void releaseSources​(@NotNull
                            SBuildAgent agent)
        Releases sources of the build configuration on specified agent only. After that full checkout will be performed when build of this configuration starts on the specified agent.
        Parameters:
        agent - agent
      • getAgentsWhereBuildConfigurationBuilt

        @NotNull
        java.util.List<SBuildAgent> getAgentsWhereBuildConfigurationBuilt()
        Returns list of agents (sorted by name) where this build configuration was ever built.
        Returns:
        see above
      • getTags

        java.util.List<java.lang.String> getTags()
        List of all tags set for builds of this configuration.
        Returns:
        union of tags for each build for the configuration.
      • forceCheckingForChanges

        void forceCheckingForChanges​(@NotNull
                                     OperationRequestor requestor)
        Starts checking for changes for all VCS roots of this build configuration
        Since:
        10.0
      • addToQueue

        @Nullable
        SQueuedBuild addToQueue​(@NotNull
                                java.lang.String triggeredBy)
        Adds build instance of the configuration to the queue with the specified requestor name.
        Parameters:
        triggeredBy - contains details about who triggered build, see also TriggeredByBuilder
        Returns:
        new queued build instance if there is no instances of this configuration in the queue, or previously added instance otherwise.
      • addToQueue

        @Nullable
        SQueuedBuild addToQueue​(@NotNull
                                BuildAgent agent,
                                @NotNull
                                java.lang.String triggeredBy)
        Adds build instance of the configuration to the queue with the specified requestor name on the specified agent (if agent is authorized).
        Parameters:
        agent - specified agent.
        triggeredBy - contains details about who triggered build, see also TriggeredByBuilder
        Returns:
        null if agent is not authorized, new SQueuedBuild instance if queue does not contain this configuration with specified agent and existing one otherwise
      • getQueuedBuilds

        @NotNull
        java.util.List<SQueuedBuild> getQueuedBuilds​(@Nullable
                                                     User user)
        If user is null or has "Show personal builds of other users" enabled, returns all queued builds including all personal builds. Otherwise, returns non-personal queued builds and personal builds of the specified user.
        Parameters:
        user - user
        Returns:
        see above
      • isCleanBuild

        boolean isCleanBuild()
        Returns if all files on an agent machine should be deleted before the build is started.
        Returns:
        true, if agent has to clean all sources and download all sources from the server before each build of the configuration.
        See Also:
        BuildTypeOptions.BT_CLEAN_BUILD
      • isShouldFailBuildIfTestsFailed

        boolean isShouldFailBuildIfTestsFailed()
        Returns true if build of the configuration has to fail if there is failed test.
        Returns:
        true, if build has to became failed after at least one test failed, regardless of build script exit code.
        See Also:
        BuildTypeOptions.BT_FAIL_IF_TESTS_FAIL
      • getExecutionTimeoutMin

        int getExecutionTimeoutMin()
        Returns duration the build allowed to run until killed by the server.
        Returns:
        build execution timeout in minutes, timeout 0 means 'forever'
        See Also:
        BuildTypeOptions.BT_EXECUTION_TIMEOUT
      • getMaximumNumberOfBuilds

        int getMaximumNumberOfBuilds()
        Returns maximum number of simultaneously running builds. 0 means there is no limit on a number of builds.
        Returns:
        see above
        See Also:
        BuildTypeOptions.BT_MAX_RUNNING_BUILDS
      • isAllowExternalStatus

        boolean isAllowExternalStatus()
        Returns if viewing of the configuration status is allowed externally.
        Returns:
        if viewing of the configuration status is allowed externally.
        See Also:
        BuildTypeOptions.BT_ALLOW_EXTERNAL_STATUS
      • moveToProject

        @Deprecated
        void moveToProject​(@NotNull
                           SProject target,
                           boolean changeScopeOfInaccessibleRoots)
                    throws InvalidVcsRootScopeException
        Deprecated.
        Moves this build configuration to the target project.
        Parameters:
        target - the destination project
        changeScopeOfInaccessibleRoots - not used since 8.0
        Throws:
        InvalidVcsRootScopeException - thrown since 8.0 if VCS roots used by this configuration will not be accessible in the target project
      • moveToProject

        void moveToProject​(@NotNull
                           SProject target)
                    throws InvalidVcsRootScopeException
        Moves this build configuration to the target project.
        Parameters:
        target - the destination project
        Throws:
        InvalidVcsRootScopeException - if VCS roots used by this configuration will not be accessible in the target project
        Since:
        8.0
      • moveToProject

        void moveToProject​(@NotNull
                           ConfigAction cause,
                           @NotNull
                           SProject target)
                    throws InvalidVcsRootScopeException
        Moves this build configuration to the target project.
        Parameters:
        cause - config action caused the change
        target - the destination project
        Throws:
        InvalidVcsRootScopeException - if VCS roots used by this configuration will not be accessible in the target project
        Since:
        9.0
      • mapVcsPath

        @Nullable
        PathMapping mapVcsPath​(@NotNull
                               java.lang.String path)
        Returns path mapping for the given full VCS path of a file if this path can correspond to any of the project's VCS roots. (TODO serganch: describe the term "full VCS path" somewhere)
        Parameters:
        path - a full path to a file (not necessarily existing)
        Returns:
        the path mapping object or null if no mapping exists
      • getExtendedName

        @NotNull
        java.lang.String getExtendedName()
        Returns the name of build configuration with additional note if the project is archived. Useful when archived build configurations should be shown together with non-archived.
        Returns:
        build configuration name
        Since:
        5.0
        See Also:
        SProject.getExtendedName()
      • getExtendedFullName

        @NotNull
        java.lang.String getExtendedFullName()
        Returns the full name of build configuration with additional note if the project is archived. Useful when archived build configurations should be shown together with non-archived.
        Returns:
        build configuration name
        Since:
        8.0
        See Also:
        SProject.getExtendedFullName()
      • getFileContent

        @NotNull
        byte[] getFileContent​(@NotNull
                              java.lang.String relativePath)
                       throws VcsException
        Get binary content of the latest version of a file related to this build type.
        Parameters:
        relativePath - - relative file path regarding to the project root, "checkout root" from vcs root should not be included
        Returns:
        - specified file content, corresponding to the build type
        Throws:
        VcsException - if some problem occurred while getting file content from the source control repository.
      • setTemplates

        void setTemplates​(@NotNull
                          java.util.List<? extends BuildTypeTemplate> templates,
                          boolean optimizeSettings)
        Replaces templates the build configuration is attached to. No settings copying occurs for templates to which the configuration ceased to be attached to as a result.
        Parameters:
        templates - Ordered list of templates, the earlier a template in the list, the higher priority its settings have
        optimizeSettings - If true, the build configuration's owner settings will be optimised by eliminating duplication with the effective settings coming from the templates.
        Since:
        2017.2
      • addTemplate

        void addTemplate​(@NotNull
                         BuildTypeTemplate template,
                         boolean optimizeSettings)
        Attach one more build configuration to a template. All previous templates will not be detached. If other templates are present in the build configuration, the newly attached templates will have the lowest priority, except for the default template (if configured in a corresponding project).
        Parameters:
        template - see above
        optimizeSettings - If true, the build configuration's owner settings will be optimised by eliminating duplication
        Since:
        2017.2
      • removeTemplates

        void removeTemplates​(@NotNull
                             java.util.Collection<? extends BuildTypeTemplate> templates,
                             boolean inlineSettings)
        Detaches build configuration from a number of templates.
        Parameters:
        templates - a collection of templates, the configuration must be attached to these (and possible some other) templates
        inlineSettings - if true, the effective settings coming from these templates are copied to the build configuration
        Since:
        2017.2
      • detachFromTemplate

        @Deprecated
        void detachFromTemplate()
        Deprecated.
        since 2017.2 use removeTemplates(Collection, boolean) instead
        Detaches build configuration from all templates, except for the default one if present. Effective template settings are copied to the build configuration itself.
        Since:
        5.0
      • setTemplatesOrder

        void setTemplatesOrder​(java.util.List<java.lang.String> templateIds)
        Imposes new order on the templates the build configuration is attached to.
        Parameters:
        templateIds - the existing template ids in the new order. The list must match currently associated templates, excluding the default template.
        Since:
        2017.2
      • getOwnTemplates

        java.util.List<? extends BuildTypeTemplate> getOwnTemplates()
        Returns a list of templates to which the build configuration is directly attached. That does not include default template.
        Returns:
        see above
        Since:
        2017.2
      • getResolvedSettings

        @NotNull
        ResolvedSettings getResolvedSettings()
        Returns resolved settings of this build configuration (with parameter references substituted)
        Returns:
        see above
        Since:
        5.0
      • getOwnDependencies

        @NotNull
        java.util.List<Dependency> getOwnDependencies()
        Returns list of own dependencies (not inherited from a template).
        Returns:
        list of own dependencies
        Since:
        5.0
      • getCustomDataStorage

        @NotNull
        CustomDataStorage getCustomDataStorage​(@NotNull
                                               java.lang.String storageId)
        Returns custom data storage associated with this build configuration. Custom data storage allows to attach custom data to a build configuration. Example of custom data is a state of some plugin associated with this build type (not configuration of the plugin). Custom data will be automatically cleaned when build configuration is removed.
        Parameters:
        storageId - - id of the storage. Custom data storageIds starting with "teamcity" are reserved for TeamCity internal usages. To reduce probability of identifiers clashing plugins can use fully qualified names of their classes or package names as storageId.
        Returns:
        custom data storage
        Since:
        5.1
      • getVcsRootInstanceEntries

        @NotNull
        java.util.List<VcsRootInstanceEntry> getVcsRootInstanceEntries()
        Returns:
        resolved VCS root entries (entries with resolved settings: VCS root parameters and checkout rules).
        Since:
        6.5
      • getVcsRootInstanceForParent

        @Nullable
        VcsRootInstance getVcsRootInstanceForParent​(@NotNull
                                                    SVcsRoot parentRoot)
        Returns:
        VCS root instance for specified parentRoot. Parent VCS root must be attached to this configuration, otherwise null will be returned.
        Since:
        6.5
      • getVcsRootInstanceEntryForParent

        @Nullable
        VcsRootInstanceEntry getVcsRootInstanceEntryForParent​(@NotNull
                                                              SVcsRoot parentRoot)
        Returns:
        VCS root instance entry for specified parentRoot. Parent VCS root must be attached to this configuration, otherwise null will be returned.
        Since:
        10.0
      • getVcsRootInstanceEntries

        @NotNull
        java.util.List<VcsRootInstanceEntry> getVcsRootInstanceEntries​(@NotNull
                                                                       java.util.Set<java.lang.String> vcsNames,
                                                                       boolean includeSettingsRoot)
        Returns entries corresponding to specified vcs support names
        Parameters:
        vcsNames - VCS support names
        includeSettingsRoot - whether settings root should be included in result
        Returns:
        see above
        Since:
        2021.2 (in BuildTypeEx since 10.0)
      • getVcsRootInstances

        @NotNull
        java.util.List<VcsRootInstance> getVcsRootInstances()
        Returns:
        collection of VCS root instances used in this build configuration.
        Since:
        6.5
      • belongsTo

        boolean belongsTo​(@NotNull
                          SProject project)
        Returns true if the specified project or some of its subprojects (not only direct) contains this build configuration.
        Specified by:
        belongsTo in interface BuildTypeIdentity
        Parameters:
        project - project
        Returns:
        see above
        Since:
        8.0
      • getOwnVcsRootEntries

        @NotNull
        java.util.List<VcsRootEntry> getOwnVcsRootEntries()
        Returns:
        build configuration own VCS roots, i.e. it does not contain VCS roots inherited from template
        Since:
        8.0
      • getDependencyReferences

        @NotNull
        java.util.List<SBuildType> getDependencyReferences()
        Returns list of build configurations directly referencing this build configuration. The returned list is filtered by current user permissions and may contain not all references.
        Returns:
        see above
      • getNumberOfDependencyReferences

        int getNumberOfDependencyReferences()
        Returns number of dependency references (the number includes all references even those which are not available because of permissions)
        Returns:
        see above
      • getBuildTypeBranchFilter

        @NotNull
        BranchFilter getBuildTypeBranchFilter()
        Returns:
        default branch filter which is applied to all branches available in this configuration since 2019.1