h1. Define promomotions
[Build promotion] can be defined in promotion setting page of a configuration like below:
!promotion.png!
The promote condition controls whether or not the promote action appears on the build page. Taking above screenshot for example:
# if a build is successful, the promote action _deploy_ will be visible while promote action _release_ will not be visible like below:
!deploy.png!
# if a build is recommended, the promote action _deploy_ and _release_ will both be visible like below:
!deploy-release.png!
# if a build is failed, no promote actions will be visible.
h1. Revision promotion and file promotion
During a promotion, QuickBuild will remember the repository revision used in source build, and use it to build destination configuration. This is called revision promotion, and it guarantees that the source build and destination build use the same set of source code. Please note that revision promotion only happens for repositories of the same name. For example, if source build is generated using source code from repository "A" and "B", and destination build is generated using source code from repository "B" and "C", only revision of repository "B" will be passed from source build to destination build.
In many cases, you may want to reuse artifacts generated in source build instead of build it from scratch when do the promotion. This is called file promotion and QuickBuild supports this via _file to promote_ setting in a promotion definition:
!file-promotion.png!
Specified promote files will be retrieved from source path under [publish directory|build publish directory] of the source build, and send to destination path under [workspace|configuration workspace] of the node running master step in destination configuration. Then you can define various build steps in destination configuration to further process the artifacts, for example to deploy them to test/production servers.
h1. Control promotion process with variables
Variables can be defined in promotion definition to control the promotion process. For example, you may have the destination build using the same version as source build following below steps:
# Specify _next build version_ of destination configuration in general setting as _$\{vars.get("promoteVersion")\}_.
# Define variable _promoteVersion_ in promotion definition and set the value to _$\{build.version\}_.
If you would like version of destination build being prompted in the above example, you may leave value of the variable _promoteVersion_ empty, and specify its prompt setting as _prompt as text input_.
At last, if you want to make sure that certain variables in destination build use the same value as in source build, you may define these variables in promotion definition to use the value _\${build.getVarValue("<name of the variable>")\}_. Assume below case:
Variable _branch_ is set to prompt for user input in source build, and it is specified as _1.0 bugfix_ when source build is triggered. At promotion time, you do not want this variable to prompt for input again, instead, you want the destination build to use the variable value already specified for source build. You can achieve this by defining variable _branch_ in promotion destination, and specify the value as _$\{build.getVarValue("branch")\}_.
h1. Permission control
Promotion permission can be controlled by promote condition. For example, if you want that the release promote action is only visible to release managers on recommended builds, you may define the promote condition like below:
!permissions.png!
{note}Please make sure that the _Release Manager_ group is assigned with _PROMOTE_BUILD_ permission over the configuration; otherwise, all promotion actions will not visible to the group. Refer to [configuration visibility and permissions] for details.{note}
h1. Change detection during promotion
In a build promotion process, changes of destination build are calculated by comparing repository revision of current destination build against previous destination build, instead of previous source build. This is well explained [here|Promote build#build changes].
[Build promotion] can be defined in promotion setting page of a configuration like below:
!promotion.png!
The promote condition controls whether or not the promote action appears on the build page. Taking above screenshot for example:
# if a build is successful, the promote action _deploy_ will be visible while promote action _release_ will not be visible like below:
!deploy.png!
# if a build is recommended, the promote action _deploy_ and _release_ will both be visible like below:
!deploy-release.png!
# if a build is failed, no promote actions will be visible.
h1. Revision promotion and file promotion
During a promotion, QuickBuild will remember the repository revision used in source build, and use it to build destination configuration. This is called revision promotion, and it guarantees that the source build and destination build use the same set of source code. Please note that revision promotion only happens for repositories of the same name. For example, if source build is generated using source code from repository "A" and "B", and destination build is generated using source code from repository "B" and "C", only revision of repository "B" will be passed from source build to destination build.
In many cases, you may want to reuse artifacts generated in source build instead of build it from scratch when do the promotion. This is called file promotion and QuickBuild supports this via _file to promote_ setting in a promotion definition:
!file-promotion.png!
Specified promote files will be retrieved from source path under [publish directory|build publish directory] of the source build, and send to destination path under [workspace|configuration workspace] of the node running master step in destination configuration. Then you can define various build steps in destination configuration to further process the artifacts, for example to deploy them to test/production servers.
h1. Control promotion process with variables
Variables can be defined in promotion definition to control the promotion process. For example, you may have the destination build using the same version as source build following below steps:
# Specify _next build version_ of destination configuration in general setting as _$\{vars.get("promoteVersion")\}_.
# Define variable _promoteVersion_ in promotion definition and set the value to _$\{build.version\}_.
If you would like version of destination build being prompted in the above example, you may leave value of the variable _promoteVersion_ empty, and specify its prompt setting as _prompt as text input_.
At last, if you want to make sure that certain variables in destination build use the same value as in source build, you may define these variables in promotion definition to use the value _\${build.getVarValue("<name of the variable>")\}_. Assume below case:
Variable _branch_ is set to prompt for user input in source build, and it is specified as _1.0 bugfix_ when source build is triggered. At promotion time, you do not want this variable to prompt for input again, instead, you want the destination build to use the variable value already specified for source build. You can achieve this by defining variable _branch_ in promotion destination, and specify the value as _$\{build.getVarValue("branch")\}_.
h1. Permission control
Promotion permission can be controlled by promote condition. For example, if you want that the release promote action is only visible to release managers on recommended builds, you may define the promote condition like below:
!permissions.png!
{note}Please make sure that the _Release Manager_ group is assigned with _PROMOTE_BUILD_ permission over the configuration; otherwise, all promotion actions will not visible to the group. Refer to [configuration visibility and permissions] for details.{note}
h1. Change detection during promotion
In a build promotion process, changes of destination build are calculated by comparing repository revision of current destination build against previous destination build, instead of previous source build. This is well explained [here|Promote build#build changes].