Continuous Delivery Scripts

Summary

continuous-delivery-scripts provides Git-based CI/CD commands for release automation, semantic versioning, changelog generation, SPDX SBOMs, third-party IP (TPIP) and licence reports, source licence headers and secret checks.

Overview

Originally forked from ARMmbed/mbed-tools-ci-scripts, the tools are written in Python but support projects in other languages through plugins. Each command handles a focused delivery task, from recording a change to auditing licences or tagging a release. The shared project delivery definition lives in one place: [ProjectConfig] in pyproject.toml. Every command reads those settings, including paths, versioning rules and the selected PROGRAMMING_LANGUAGE, regardless of the project's language or CI system. The selected plugin then uses appropriate ecosystem tools: for example, GoReleaser for Go releases or wheel and Twine for Python packages. Consult the plugin guides for language-specific requirements; native build manifests and credentials may still be needed. See the project configuration guide for the pyproject.toml fields required by each workflow.

Run the same commands locally or in any CI system that can check out the project's Git repository and install the required tools. This avoids infrastructure lock-in: the team can decide which CI system suits its project, including after the delivery workflow has been defined.

Usage and documentation

Start with the common use cases below, then follow the task guides for prerequisites, outputs and CI examples. The GitHub Pages site publishes those guides alongside the API reference when release documentation is regenerated. For individual commands and their typical developer or CI usage, see the command-line tools table.

To include your own Markdown guides in generated documentation, configure their source and published folder in [ProjectConfig]:

DOCUMENTATION_GUIDES_DIR = "guides"
DOCUMENTATION_GUIDES_OUTPUT_FOLDER = "guides"

Add guides/index.md with links to the other .md files and run cd-generate-docs. It renders the guides to HTML alongside the API reference; the default published folder is guides/. Keep the Markdown source outside the documentation output, which the generator clears before each build. See generating code documentation.

Common use cases

Generate an SPDX SBOM and third-party IP report

For a project whose language plugin provides package metadata, generate SPDX tag-value documents for the project and its dependencies alongside an HTML third-party IP / TPIP licence report. Use these as inputs to an OpenChain licence-compliance workflow:

mkdir -p spdx-output
cd-generate-spdx --output-dir spdx-output

The destination directory must exist. Check that your plugin supports metadata reporting: the command can finish without producing reports when it does not. For SPDX documents, define PROJECT_UUID and [spdx] namespace settings in pyproject.toml as described under SPDX document identity. See SPDX generation and TPIP reporting for outputs and prerequisites.

Automate semantic releases and changelogs

Record a change as a news fragment, then preview the next release version:

cd-create-news-file "Fix dependency resolution" --type bugfix
cd-determine-version --release-type release

In a configured release workflow, cd-generate-news --release-type release builds the changelog from those fragments; cd-tag-and-release handles Git tags and publication through the selected language plugin. See changelog management and release automation.

Manage source licence and copyright headers

Run cd-license-files to apply the configured source-file headers when the language plugin supports them. See the licence header guide.

Prevent secrets from leaking through Git

Accidentally committing a password or API token can expose it to others and leave it in repository history. Keep a reviewed detect-secrets registry and check Git-tracked files locally or in CI before a change is merged:

cd-detect-secrets --registry-file .secrets.baseline

The check fails on new findings. Use cd-record-secrets only to record values the team has reviewed and accepted, rather than to hide real credentials. See checking for secrets and recording accepted findings.

Releases

For release notes and a history of changes of all production releases, please see the following:

• Changelog

For all available versions, see the:

• PyPI Release History

Versioning

The version scheme follows PEP 440 and Semantic Versioning. Production releases use:

• <major>.<minor>.<patch>

Beta releases give early access to experimental features. They may be unstable, and interfaces introduced in a beta release may change without notice. Beta releases use:

• <major>.<minor>.<patch>-beta.<pre-release-number>

Installation

It is recommended that a virtual environment such as Pipenv is used for all installations to avoid Python dependency conflicts.

To install the most recent production quality release use:

pip install continuous-delivery-scripts

To install a specific release:

pip install continuous-delivery-scripts==<version>

Command-line tools

Following the Unix tools philosophy, the package installs focused command-line tools. Run them within a project configured by pyproject.toml, such as this project. Use <command> --help for all available options; release types are development, beta and release. The final column shows where each command is most likely to be used; developer checks can also be incorporated into CI. These are the same commands whichever CI system the team chooses.

For example, cd-create-news-file "Fix dependency resolution" --type bugfix adds a news fragment. For release workflow details, see the development guide.

For GitHub automation that performs authenticated clone or fetch operations, see GitHub Token Authentication.

GitHub Token Authentication

When git operations need to retry against GitHub over HTTPS, this project now uses the credential layout https://x-access-token:<token>@github.com/<owner>/<repo>.git.

This means the token is sent in the password position with x-access-token as the username, which is the format GitHub accepts for workflow-generated and other non-OAuth tokens used by automation.

Older https://<token>:x-oauth-basic@github.com/... URLs were tied to OAuth-style credentials and could reject tokens created dynamically during CI/CD flows.

Project Structure

The main parts of the repository are:

• .github - CI and GitHub configuration files.
• docs/ - Generated GitHub Pages guides and API reference (rebuilt on release).
• guides/ - Markdown source for task-based documentation.
• llms.txt - A concise map of the published documentation.
• continuous_delivery_scripts/ - Python source files and language plugins.
• news/ - Collection of news files for unreleased changes.
• tests/ - Unit and integration tests.

Getting Help

• For interface definition and usage documentation, please see GitHub Pages.
• For a list of known issues and possible workarounds, please see Known Issues.
• To raise a defect or enhancement please use GitHub Issues.

Contributing

• We are committed to fostering a welcoming community, please see our Code of Conduct for more information.
• For ways to contribute to the project, please see the Contributions Guidelines
• For a technical introduction into developing this package, please see the Development Guide