fossil-ci

View documentation for the original command

$ tldr fossil commit

fossil ci
    [--status STATUS]
    [--tag TAG]
    [--url URL]
    [--user USER]
    [--hash UUID | --branch BRANCH | --checkin UUID]
    [--desc TEXT]
    [--ci-name NAME]
    [--verbose]
    [--repository FILE]

--status STATUS
    Sets the CI status. STATUS can be 'ok' (success), 'fail' (failure), 'error' (system error), or 'pending' (in progress).

--tag TAG
    Specifies a CI tag (e.g., 'ci/build/linux-amd64' or 'ci/test/unit') to categorize the CI result.

--url URL
    Provides a URL pointing to the detailed output, logs, or dashboard of the CI job for more information.

--user USER
    Specifies the user or system that performed the CI operation (e.g., 'jenkins', 'gitlab-ci', 'github-actions').

--hash UUID
    The UUID of the specific check-in for which the CI status applies. Typically provided by the CI environment.

--branch BRANCH
    Specify the branch being built/tested. If --hash or --checkin is not provided, the CI result will be linked to the tip of this branch.

--checkin UUID
    Synonym for --hash, specifying the check-in UUID. Use either --hash or --checkin.

--desc TEXT
    Adds an optional short description or message for the CI result, often summarizing the outcome.

--ci-name NAME
    A unique identifier for the CI system or workflow that produced the result (e.g., 'Jenkins-Project-X', 'GitHub-Actions-Lint').

--verbose
    Enables verbose output, displaying more details about the command's execution and internal operations.

--repository FILE
    Specifies the path to the Fossil repository file. If omitted, the command attempts to find the repository in the current directory or parent directories.

The fossil-ci command, usually invoked as fossil ci, is a subcommand of the Fossil SCM (Self-Contained Distributed Software Configuration Management System). Its primary purpose is to enable continuous integration (CI) systems to communicate build and test results back to the Fossil repository. When a CI job completes, fossil-ci is used to record the status (e.g., success, failure, pending), associate it with a specific check-in, and optionally provide a URL to the CI job's output and a descriptive tag. This allows developers to see the CI status directly within the Fossil repository's web interface, providing immediate feedback on the health of the codebase.

The fossil-ci command expects to be run within a Fossil repository clone or with the --repository option pointing to a valid repository file. It requires appropriate write permissions to record CI events. It's crucial for CI systems to correctly identify the check-in UUID (via --hash or --checkin) to ensure CI results are associated with the precise code version. Incorrect usage might lead to CI status not being displayed or being displayed for the wrong commit. The command generally returns a non-zero exit code on failure to record the CI status, which CI systems can use to determine script success.

Typically, a CI script will check out a Fossil repository, perform build and test steps, and then invoke fossil ci to report the outcome before cleanup. For example, after a successful build, a script might run:
fossil ci --status ok --tag "ci/build/linux" --url "$CI_JOB_URL" --hash "$FOSSIL_COMMIT_UUID" --ci-name "MyBuildSystem"
This integrates the CI status seamlessly into Fossil's built-in web interface, allowing anyone browsing the repository to see the health of specific check-ins without leaving the Fossil UI.

The CI status recorded by fossil-ci is prominently visible in the Fossil web UI. For instance, on the timeline or individual check-in pages, entries that have associated CI results will often display a distinctive icon (e.g., a green checkmark for 'ok', a red X for 'fail') indicating their build status. Clicking on these icons typically leads to the URL provided by the --url option, directing users to the detailed CI job output.

The continuous integration features, including the fossil ci command, were introduced in Fossil SCM to provide native support for tracking build and test statuses directly within the repository. This functionality enhances Fossil's self-contained nature by allowing CI results to be stored and viewed alongside the source code, tickets, and wiki, rather than relying solely on external CI dashboards. Its development reflects the growing importance of automated testing and build processes in modern software development workflows, making Fossil a more comprehensive SCM solution for projects utilizing CI.

fossil(1), fossil ui(1), fossil status(1), fossil sync(1)