Deploying¶
The deploy
section¶
At the end of the build process, dbuild can automatically upload the generated artifacts to one or more
repositories. The deploy
section in the build configuration file is optional; it consists of a sequence
of deploy records, with the following structure:
{
build: {projects:..., options:...}
options: {
deploy: [{
"uri" : <repository-uri>,
"credentials" : <optional-credentials>,
"projects" : [<project1>,<project2>,...]
"sign" : <optional-sign-info>
"index" : <optional-index-data>
}, ...]
...
}
}
Within each record:
- repository-uri
A string specifying the URI of the desired repository; it can be written either with or without a trailing slash. It can be one of the following:
file:///path/to/local/repository
- The artifacts will be copied to the local file system. The directory will be created
if it does not exist. Existing files in that directory with colliding names will be
overwritten; the other files that were previously in the same directory will be left
untouched. A relative path can be written like
file:path
. http://hostname:port/path1/path2
- A Maven or Ivy (or other) remote repository. It can also use the "https" scheme, and a custom port may optionally be specified. A credentials file is required (see later).
s3://bucket/path1/path2
- The artifacts will be uploaded to an Amazon S3 bucket. Credentials must be specified.
ssh://hostname/path1/path2
- The artifacts will be uploaded using scp (sftp). The supplied
credentials (username and password) corresponding to that hostname will be used for
authentication. However, if the public key of this system has been added to the authorized
keys of the remote system (passwordless authentication), dbuild will be able to use those
keys to authenticate as well; the password specified in the credentials will be ignored.
In order to use key-based authentication, the private key of the system on which
dbuild runs must be in
~/.ssh/id_rsa
; the passphrase must be empty. bintray:/owner/repo/package/version[#release]
- The artifacts will be uploaded to Bintray, and optionally released. Exactly four parts must be defined in the path, defining the Bintray parameters. You can optionally append to the uri the fragment "#release" if you wish a release to be published at the end of deploy; if the fragment is not present or is not "#release", the artifacts will be left pending in the Bintray repository. If the uri contains the query component "?override=1", then new artifacts will overwrite existing ones with the same name and path already in the repository (if published within the last 180 days), otherwise an attemp to overwrite artifacts will return a "409" HTTP error code. Please note that if you have both a query and a fragment in the uri, then the query must come first. The uri format above will work for both generic as well as for Maven-style bintray repositories.
null:null
- The artifacts will be ignored, without actually being uploaded anywhere. This
option can be used in conjunction with the index generation facility, described
below. By using the
null:null
scheme, it is possible to generate an index corresponding to a given subset of artifacts, without having to upload the given artifacts at the same time.
- credentials
- A properties file containing at least the properties "host", "user", and "password". The
value of the "host" property must match the hostname or the bucket name. In the case of
Amazon S3, the property "user" contains the Access Key ID, while the property "password"
contains the Secret Access Key. The credentials specification should be omitted for
file
repositories. For Bintray, the "host" must be "api.bintray.com", the Bintray username used as "user", and the Bintray API key must be specified as the password. For Bintray the credentials file may be the standard "/home/user/.bintray/.credentials" file. - projects
- An optional list of project names, from the ones specified in the same build configuration file. Only the artifacts generated by this projects will be deployed to the repository specified. If not present, the artifacts of all projects will be uploaded. If present, but empty, none will be uploaded (useful to disable temporarily the section). The string "." refers to the root build, and is equivalent to "all the projects".
In place of a project name, it is also possible to specify a limited set of subprojects from a certain project. That will also work for the Scala build; it is possible to deploy to a certain repository only scala-library and scala-compiler, for example. The syntax is:
{
"from" : <project-name>,
"publish" : [<subproject1>,<subproject2>,...]
}
Only the projects that completed their build succesfully will be deployed; the failed ones will be skipped with an error message. If there is only one project in the list, either a string or a from/publish record, the square brackets in the list can be omitted.
- index
- An optional descriptor for the generation of index data; a full description is below.
- sign
- If this optional section is included, the artifacts will be signed with the specified key information before being deployed. The relevant information is supplied as:
{
"passphrase" : <passphrase-file>
"id" : <optional-secret-key-id>
"secret-ring" : <optional-secret-ring-file>
}
- passphrase
- This is the only required field: it is the path to a text file that contains the passphrase that should be used for signing.
- id
- If the keyring contains several keys, this field can be used to specify the id of
the key that should be used. It must be a 16-characters hexadecimal string; you
can find the necessary value by using
gpg --list-keys --with-colon
. - secret-ring
- If the file containing your keys is in a non-standard location, you can specify the
file path here. By default, it will use
~/.gnupg/secring.gpg
Using such a sequence of deploy records, it is possible to deploy diffent sets of artifacts to different repositories, or to upload the same artifacts to multiple repositories during a single run. Since signing is specified within a deploy record, the same artifacts can be signed with different keys for different repositories, during deployment.
For example:
"deploy":[
{
uri="file:///home/user/files/repo"
projects:["genjavadoc",{from:"akka",subprojects:"akka-actor"}]
},
{
uri="s3://s3-testBucket/repo"
credentials="/home/user/.credentials-s3"
projects="scala-arm"
},
{
uri="http://localhost:8088/artifactory/repos/test1"
credentials="/home/user/.ivy2/.credentials-local"
projects=["genjavadoc","akka","scala","scala-arm"]
sign: {
passphrase:"/home/user/.passphrase"
id:"0A6C9FC933CA9D7E"
}
}
]
Note
If you encounter an error 404
while deploying, that may be caused by an attempt to upload a checksum file
(.sha1 or .md5) that has no corresponding main file. This should normally never happen, but it may be the result
of some anomalous build/clean error during the build stage.
Similarly, an error 409
may occur when the checksum file that was generated during the build stage does
not match the checksum that was calculated on the server during the deployment of the main file. Again, this
may be the result of some unexpected build anomaly, or it may be caused by a failure while uploading the artifact
files to the repository server.
Index generation¶
Optionally, dbuild can generate a file containing a summary of the modules whose artifacts have been deployed to
each repository. You can just define the index
field in the relevant deploy configuration (above), as follows:
{
"uri" : <target-repository>,
"credentials" : <optional-credentials>,
"filename" : <index-file-name>,
}
The fields are as follows:
- uri
- The target repository or directory where the index file will be stored; this can be either the same uri as the one in the deploy block, or a different target. This field has the same format as the uri in the deploy configuration section above.
- credentials
- If the target for the index file requires credentials, please supply them here, following the format described above. // Specified in ISO-8601 format, parsed via com.fasterxml.jackson.databind.util.ISO8601DateFormat
- filename
- This is the name of the index file that will be stored in the repository.
Next: Notifications.
Contents