home | help 
bdep-ci(1)		     General Commands Manual		      bdep-ci(1)

NAME
     bdep-ci - submit project test request to CI server

SYNOPSIS
     bdep ci [options] [cfg-spec] [pkg-spec]

     cfg-spec = (@cfg-name | --config|-c cfg-dir)... | --all|-a | --forward
     pkg-spec = (pkg | (--directory|-d pkg-dir))... | prj-spec
     prj-spec = --directory|-d prj-dir

DESCRIPTION
     The ci command submits the project packages test request to a CI server.

     If  no  project or package directory is specified, then the current working
     directory is assumed. If no configuration is specified,  then  the  default
     configurations are used. If the specified directory is a project directory,
     then  all the packages initialized in the configurations are submitted, un-
     less the --forward option is specified (see below). See  bdep-projects-con-
     figs(1) for details on specifying projects and configurations.

     A	CI request consists of the specified packages and their versions as well
     as the project's remote version control repository URL corresponding to the
     current (local) state of the project. The CI server should be able to fetch
     these package versions from this repository as  well  as  any  dependencies
     from this repository or its prerequisite/complement repositories, according
     to each package's repositories.manifest.

     If  the CI server is not explicitly specified with the --server option, the
     request is submitted to ci.cppget.org by default.

     Unless the remote repository URL is specified with the --repository option,
     it will be automatically derived from the version control's  "remote"  URL.
     In  case of git(1), it will be based on the remote.origin.url configuration
     value unless overridden with remote.origin.build2Url. The repository URL is
     then adjusted to corresponding to the current (local) state of the project.
     In case of git(1), the current branch and commit id are added as the repos-
     itory URL fragment (see bpkg-repository-types(1) for details).

     Some package manifest values can be overridden as part of	the  CI  request
     submission  using	the  --override  and --overrides-file options as well as
     their  --builds,  --build-config,	--target-config,  --package-config,  and
     --build-email  shortcuts.	This is primarily useful for specifying alterna-
     tive build configurations and/or build notification emails. For example:

     $ bdep ci --builds gcc
     $ bdep ci --builds network/gcc
     $ bdep ci --target-config 'linux*-gcc*'
     $ bdep ci --package-config network
     $ bdep ci --build-config 'network/linux*-gcc*'

     $ bdep ci --override \
       'default-build-config: config.foo.cache=true config.foo.buffer=16'

     $ bdep ci --override 'mytest-build-config: config.foo.cache=true' \
       --package-config mytest

     $ bdep ci --override 'build-auxiliary: *-postgresql_16'

     Manifest overrides other than [*-]build-auxiliary[-*] override  the  entire
     value  group  that  they belong to. The [*-]build-auxiliary[-*] values only
     override the matching values, which are expected to already be  present  in
     the  package manifest.  Currently, the following value groups/values can be
     overridden. The build-*email group is overridden by default as if by speci-
     fying an empty build email.

     build-email build-{warning,error}-email
     builds build-{include,exclude}
     build-bot
     *-builds *-build-{include,exclude}
     *-build-bot
     *-build-config
     *-build-email *-build-{warning,error}-email

     [*-]build-auxiliary[-*]

     For the package configuration-specific build constraint, email,  auxiliary,
     and  custom  bot public key overrides, the corresponding configuration must
     exist in the package manifest. In contrast, the package configuration over-
     ride (*-build-config) adds a new configuration if it doesn't exist and  up-
     dates  the arguments of the existing configuration otherwise. In the former
     case, all the potential build constraint, email, auxiliary, and custom  bot
     public  key  overrides for such a newly added configuration must follow the
     corresponding *-build-config override.

     Note that the build constraints group values (both common and build package
     configuration-specific)  are  overridden	hierarchically	 so   that   the
     [*-]build-{include,exclude}   overrides   don't   affect	the   respective
     [*-]builds values.

     Note also that the common and build  package  configuration-specific  build
     constraints  group  value	overrides  are mutually exclusive. If the common
     build constraints are overridden, then all the configuration-specific  con-
     straints  are removed. Otherwise, if any configuration-specific constraints
     are overridden, then for the remaining configurations the build constraints
     are reset to builds: none.

     Similar to the build constraints groups, the common and build package  con-
     figuration-specific  custom bot public key value overrides are mutually ex-
     clusive. If the common build custom bot public keys  are  overridden,  then
     all  the  configuration-specific custom bot public keys are removed. Other-
     wise, if any configuration-specific custom bot public keys are  overridden,
     then  for	the remaining configurations the custom bot public keys are left
     unchanged.

     Similar to the above, the common and build  package  configuration-specific
     build  emails  group  value overrides are mutually exclusive. If the common
     build emails are overridden, then all the configuration-specific emails are
     removed. Otherwise, if any configuration-specific	emails	are  overridden,
     then  for	the  remaining	configurations the build emails are reset to the
     empty values and the build warning and error emails are removed (which  ef-
     fectively disables email notifications for such configurations).

     If  supported by the CI service, a package can be tested interactively in a
     specific build configuration using the  --interactive|-i  option.	In  this
     mode  the CI service provides the login information for the execution envi-
     ronment and pauses the testing at the specified breakpoint.

     While the exact interpretation of the CI request depends  on  the	specific
     service,  normally, the CI server will respond with a reference that can be
     used to query the results. See Package CI (#ci) for details on the  CI  re-
     quest handling.

     If  the --forward option is specified then the forwarded configurations are
     used instead of the default configurations. In particular, this means  that
     in  this mode the project doesn't need to be initialized and all that's re-
     quired is for package's source directories to be configured to  forward  to
     an  out  of  source  build configuration (see b(1) for details on forwarded
     configurations). This, for example, can be used  to  submit  packages  that
     don't use the standard version.

CI OPTIONS
     --yes|-y
	    Don't prompt for confirmation before submitting.

     --interactive|-i cf[:bp]
	    Test the package interactively in the specified build configuration,
	    pausing the execution at the specified breakpoint. The build config-
	    uration  is  a  target configuration (tc), optionally for a specific
	    package configuration (pc) and/or for a specific target (tg):

	    cf = [pc/]tc | pc/tc/tg

	    Refer to the --build-config option for details on the build configu-
	    ration component semantics. Note that for interactive  testing  they
	    should  identify a single build configuration. Failed that, the test
	    request will be aborted.

	    Valid breakpoint values are none (don't  stop),  error  (stop  after
	    first  error), warning (stop after first warning), as well as the CI
	    service-specific step ids in which case the execution  stops  before
	    performing	the specified step (see bbot worker step ids (bbot#arch-
	    worker)). If no breakpoint is specified, then error is assumed.

     --server url
	    CI server to submit the request to.

     --repository url
	    Remote repository URL for the project.

     --override name:value
	    Package manifest value override. Repeat this option to override mul-
	    tiple values.

     --overrides-file file
	    Read manifest value overrides from the specified  manifest	fragment
	    file.  Repeat this option to specify multiple override files.

     --builds [pc/]class-expr
	    Shortcut for the following option:

	    --override [pc-]builds:class-expr

	    Repeat  this  option  to specify multiple build target configuration
	    classes.

     --build-config pc/tc[/tg]
	    Shortcut for the following options sequence:

	    [--override pc-builds:all]
	    --override pc-build-include:tc[/tg]
	    --override pc-build-exclude:**

	    The first override is omitted from the above  sequence  if	the  pc-
	    builds override is specified on the command line.

	    Repeat this option to specify multiple build configurations.

     --target-config tc[/tg]
	    Shortcut for the following options sequence:

	    [--override builds:all]
	    --override build-include:tc[/tg]
	    --override build-exclude:**

	    The  first override is omitted from the above sequence if the builds
	    override is specified on the command line.

	    Repeat this option to specify multiple build target configurations.

     --package-config pc
	    Shortcut for the following options sequence:

	    --override pc-builds:...
	    --override pc-build-include:...
	    --override pc-build-exclude:...

	    Where the override values are the build constraints for  the  speci-
	    fied build package configuration from the package manifest.

	    Repeat this option to specify multiple build package configurations.

     --build-email email
	    Shortcut for the following option:

	    --override build-email:email

     --force check
	    Force  submission, disabling the specified check. Repeat this option
	    to disable multiple checks.

     --simulate outcome
	    Simulate the specified outcome of the CI  process  without	actually
	    performing any externally visible actions (such as testing the pack-
	    ages  or  publishing the result). The commonly used outcome value is
	    success. For other recognized outcomes refer to the CI service docu-
	    mentation.

     --forward
	    Use the forwarded configuration for each package instead of the  de-
	    fault configuration.

     --all|-a
	    Use all build configurations.

     --config|-c dir
	    Specify the build configuration as a directory.

     --directory|-d dir
	    Assume  project/package is in the specified directory rather than in
	    the current working directory.

     --config-name|-n name
	    Specify the build configuration as a name.

     --config-id num
	    Specify the build configuration as an id.

COMMON OPTIONS
     The common options are summarized below with a  more  detailed  description
     available in bdep-common-options(1).

     -v     Print essential underlying commands being executed.

     -V     Print all underlying commands being executed.

     --quiet|-q
	    Run quietly, only printing error messages.

     --verbose level
	    Set the diagnostics verbosity to level between 0 and 6.

     --stdout-format format
	    Representation format to use for printing to stdout.

     --jobs|-j num
	    Number of jobs to perform in parallel.

     --progress
	    Display  progress  indicators  for	long-lasting operations, such as
	    network transfers, building, etc.

     --no-progress
	    Suppress progress indicators for long-lasting  operations,	such  as
	    network transfers, building, etc.

     --diag-color
	    Use color in diagnostics.

     --no-diag-color
	    Don't use color in diagnostics.

     --bpkg path
	    The  package manager program to be used for build configuration man-
	    agement.

     --bpkg-option opt
	    Additional option to be passed to the package manager program.

     --build path
	    The build program to be used to build packages.

     --build-option opt
	    Additional option to be passed to the build program.

     --curl path
	    The curl program to be used for network operations.

     --curl-option opt
	    Additional option to be passed to the curl program.

     --offline
	    Do not attempt to download resources (packages, repository metadata,
	    etc), instead taking them from the local fetch  cache  if  available
	    and failing otherwise.

     --no-fetch-cache
	    Disable  local  caching  of download resources (packages, repository
	    metadata, etc).

     --fetch-cache mode
	    Comma-separated list of local fetch cache modes.

     --fetch-cache-session id
	    The local fetch cache session.

     --sqlite-synchronous mode
	    Filesystem synchronization mode for the project SQLite database.

     --pager path
	    The pager program to be used to show long text.

     --pager-option opt
	    Additional option to be passed to the pager program.

     --options-file file
	    Read additional options from file.

     --default-options dir
	    The directory to load additional default options files from.

     --no-default-options
	    Don't load default options files.

DEFAULT OPTIONS FILES
     See bdep-default-options-files(1) for an overview of  the	default  options
     files.  For the ci command the search start directory is the project direc-
     tory. The following options files are searched for in each  directory  and,
     if found, loaded in the order listed:

     bdep.options
     bdep-ci.options

     The following ci command options cannot be specified in the default options
     files:

     --directory|-d

BUGS
     Send bug reports to the users@build2.org mailing list.

COPYRIGHT
     Copyright (c) 2014-2026 the build2 authors.

     Permission is granted to copy, distribute and/or modify this document under
     the terms of the MIT License.

bdep 0.18.0			   April 2026			      bdep-ci(1)
home | help