CI/CD - New updates to default branch¶

File to use: ci_cd_updated_default_branch.yml

Keep your permanent_dependencies_branch branch up-to-date with changes in your main development branch, i.e., the default_repo_branch.

Furthermore, this workflow can optionally update the latest mike+MkDocs+GitHub Pages-framework documentation release alias, which represents the default_repo_branch. The workflow also alternatively supports the Sphinx framework.

Warning

If a PAT is not passed through for the PAT secret and GITHUB_TOKEN is used, beware that any other CI/CD jobs that run for, e.g., pull request events, may not run since GITHUB_TOKEN-generated PRs are designed to not start more workflows to avoid escalation. Hence, if it is important to run CI/CD workflows for pull requests, consider passing a PAT as a secret to this workflow represented by the PAT secret.

Important

If this is to be used together with the CI - Update dependencies PR workflow, the pr_body_file supplied to that workflow (if any) should match the update_depednencies_pr_body_file input in this workflow and be immutable within the first 8 lines, i.e., no check boxes or similar in the first 8 lines. Indeed, it is recommended to not supply pr_body_file to the CI - Update dependencies PR workflow as well as to not supply the update_dependencies_pr_body_file in this workflow in this case.

Note

Concerning the changelog generator, the specific input changelog_exclude_labels defaults to a list of different labels if not supplied, hence, if supplied, one might want to include these labels alongside any extra labels. The default value is given here as a help:
'duplicate,question,invalid,wontfix'

If used together with the Update API Reference in Documentation, please align the relative input with the --relative option, when running the hook. See the proper section to understand why and how these options and inputs should be aligned.

Expectations¶

The repository contains the following:

(required) At least one Python package exists that can be pointed to for the package_dirs input.
(required) Only if also updating the documentation, then the documentation should be contained in a root docs directory.
(required) Only if also updating the documentation, then a root README.md file must exist and desired to be used as the documentation's landing page if the update_docs_landing_page is set to true, which is the default.

Inputs¶

The following inputs are general inputs for the workflow as a whole.

Name	Description	Required	Default	Type
`git_username`	A git username (used to set the 'user.name' config option).	*Yes*		string
`git_email`	A git user's email address (used to set the 'user.email' config option).	*Yes*		string
`runner`	The runner to use for the workflow. Note, the callable workflow expects a Linux/Unix system..	No	ubuntu-latest	string
`default_repo_branch`	The branch name of the repository's default branch. More specifically, the branch the PR should target.	No	main	string
`test`	Whether to do a "dry run", i.e., run the workflow, but avoid pushing to 'permanent_dependencies_branch' branch and deploying documentation (if 'update_docs' is 'true').	No	`false`	boolean
`pip_index_url`	A URL to a PyPI repository index.	No	`https://pypi.org/simple/`	string
`pip_extra_index_urls`	A space-delimited string of URLs to additional PyPI repository indices.	No	Empty string	string

Inputs related to updating the permanent dependencies branch.

Name	Description	Required	Default	Type
`update_dependencies_branch`	Whether or not to update the permanent dependencies branch.	No	`true`	boolean
`permanent_dependencies_branch`	The branch name for the permanent dependency updates branch.	No	ci/dependency-updates	string
`update_dependencies_pr_body_file`	Relative path to a PR body file from the root of the repository, which is used in the 'CI - Update dependencies PR' workflow, if used. Example: `'.github/utils/pr_body_update_deps.txt'`.	No	Empty string	string

Inputs related to building and releasing the documentation.

Name	Description	Required	Default	Type
`update_docs`	Whether or not to also run the 'docs' workflow job.	No	`false`	boolean
`update_python_api_ref`	Whether or not to update the Python API documentation reference. Note: If this is 'true', 'package_dirs' is required.	No	`true`	boolean
`package_dirs`	A multi-line string of paths to Python package directories relative to the repository directory to be considered for creating the Python API reference documentation. Example: `'src/my_package'`. Important: This is required if 'update_docs' and 'update_python_api_ref' are 'true'. See also Single vs multi-line input.	Yes (if 'update_docs' and 'update_python_api_ref' are 'true')		string
`update_docs_landing_page`	Whether or not to update the documentation landing page. The landing page will be based on the root README.md file.	No	`true`	boolean
`python_version`	The Python version to use for the workflow. Note: This is only relevant if `update_pre-commit` is `true`.	No	3.9	string
`doc_extras`	Any extras to install from the local repository through 'pip'. Must be encapsulated in square parentheses (`[]`) and be separated by commas (`,`) without any spaces. Example: `'[docs]'`.	No	Empty string	string
`relative`	Whether or not to use install the local Python package(s) as an editable.	No	`false`	boolean
`exclude_dirs`	A multi-line string of directories to exclude in the Python API reference documentation. Note, only directory names, not paths, may be included. Note, all folders and their contents with these names will be excluded. Defaults to `'__pycache__'`. Important: When a user value is set, the preset value is overwritten - hence `'__pycache__'` should be included in the user value if one wants to exclude these directories. See also Single vs multi-line input.	No	__pycache__	string
`exclude_files`	A multi-line string of files to exclude in the Python API reference documentation. Note, only full file names, not paths, may be included, i.e., filename + file extension. Note, all files with these names will be excluded. Defaults to `'__init__.py'`. Important: When a user value is set, the preset value is overwritten - hence `'__init__.py'` should be included in the user value if one wants to exclude these files. See also Single vs multi-line input.	No	__init__.py	string
`full_docs_dirs`	A multi-line string of directories in which to include everything - even those without documentation strings. This may be useful for a module full of data models or to ensure all class attributes are listed. See also Single vs multi-line input.	No	Empty string	string
`full_docs_files`	A multi-line string of relative paths to files in which to include everything - even those without documentation strings. This may be useful for a file full of data models or to ensure all class attributes are listed. See also Single vs multi-line input.	No	Empty string	string
`special_file_api_ref_options`	A multi-line string of combinations of a relative path to a Python file and a fully formed mkdocstrings option that should be added to the generated MarkDown file for the Python API reference documentation. Example: `my_module/py_file.py,show_bases:false`. Encapsulate the value in double quotation marks (`"`) if including spaces ( ). Important: If multiple `package_dirs` are supplied, the relative path MUST include/start with the appropriate 'package_dir' value, e.g., `"my_package/my_module/py_file.py,show_bases: false"`. See also Single vs multi-line input.	No	Empty string	string
`landing_page_replacements`	A multi-line string of replacements (mappings) to be performed on README.md when creating the documentation's landing page (index.md). This list always includes replacing `'docs/'` with an empty string to correct relative links, i.e., this cannot be overwritten. By default `'(LICENSE)'` is replaced by `'(LICENSE.md)'`. See also Single vs multi-line input.	No	(LICENSE),(LICENSE.md)	string
`landing_page_replacement_separator`	String to separate a mapping's 'old' to 'new' parts. Defaults to a comma (`,`).	No	,	string
`changelog_exclude_tags_regex`	A regular expression matching any tags that should be excluded from the CHANGELOG.md.	No	Empty string	string
`changelog_exclude_labels`	Comma-separated list of labels to exclude from the CHANGELOG.md.	No	Empty string	string
`docs_framework`	The documentation framework to use. This can only be either `'mkdocs'` or `'sphinx'`.	No	mkdocs	string
`system_dependencies`	A single (space-separated) or multi-line string of Ubuntu APT packages to install prior to building the documentation. See also Single vs multi-line input.	No	Empty string	string

Finally, inputs related only to the Sphinx framework when building and releasing the documentation.

Name	Description	Required	Default	Type
`sphinx-build_options`	Single (space-separated) or multi-line string of command-line options to use when calling `sphinx-build`. See also Single vs multi-line input.	No	Empty string	string
`docs_folder`	The path to the root documentation folder relative to the repository root.	No	docs	string
`build_target_folder`	The path to the target folder for the documentation build relative to the repository root.	No	site	string

Secrets¶

Name	Description	Required
`PAT`	A personal access token (PAT) with rights to update the `permanent_dependencies_branch`. This will fallback on `GITHUB_TOKEN`.	No

Usage example¶

The following is an example of how a workflow may look that calls CI/CD - New updates to default branch. It is meant to be complete as is.

name: CI - Activate auto-merging for Dependabot PRs

on:
  push:
    branches:
    - stable

jobs:
  updates-to-stable:
    name: Call external workflow
    uses: SINTEF/ci-cd/.github/workflows/ci_cd_updated_default_branch.yml@v2.8.3
    if: github.repository_owner == 'SINTEF'
    with:
      git_username: "Casper Welzel Andersen"
      git_email: "CasperWA@github.com"
      default_repo_branch: stable
      permanent_dependencies_branch: "ci/dependency-updates"
      update_docs: true
      package_dirs: |
        my_python_package
        my_other_python_package
      doc_extras: "[docs]"
      exclude_files: __init__.py,config.py
      full_docs_dirs: models
      landing_page_replacements: "(LICENSE);(LICENSE.md)|(tools);(../tools)"
      landing_page_replacements_mapping_separator: ";"
    secrets:
      PAT: ${{ secrets.PAT }}