diff --git a/.project-metadata.json b/.project-metadata.json index 96971ea..9562b8d 100644 --- a/.project-metadata.json +++ b/.project-metadata.json @@ -2,7 +2,7 @@ "name": "cicee", "description": "Runs continuous integration workloads via docker-compose, locally or on a build server.", "title": "Continuous Integration Containerized Execution Environment (CICEE)", - "version": "1.0.0", + "version": "1.1.0", "ciEnvironment": { "variables": [ { diff --git a/docs/use/ci-library.md b/docs/use/ci-library.md index 20d3f72..963cd47 100644 --- a/docs/use/ci-library.md +++ b/docs/use/ci-library.md @@ -121,9 +121,18 @@ Once the CI library is loaded, the continuous integration execution environment All CI actions implicitly require this function to be executed. Its purpose is to provide a consistent execution environment for project-level activities. For example, by using a consistent `BUILD_PACKAGED_DIST` variable, CI actions creating an output zip file, NPM package, or APK can all place their artifacts in consistent locations. +#### Initialization Overrides + +The following environment variables may be provided to override inferred configuration. + +* `PROJECT_METADATA` - Project metadata JSON file. Default: `${PROJECT_ROOT}/project-metadata.json` or `${PROJECT_ROOT}/package.json` +* `PROJECT_ROOT` - Project root directory. + +#### Initialization Effect + Expected environment available to all CI actions, after `ci-env-init` is executed: -_Contextual_ +##### Contextual Environment Variables * `PROJECT_NAME` - Project name. By convention this should be in lower kebab case. I.e., multi-word-project-name. This will be used to pattern conventional output ths, e.g., as part of a zip archive file name. * `PROJECT_ROOT` - Project root directory. @@ -136,7 +145,7 @@ _Contextual_ * `CURRENT_GIT_BRANCH` - Current Git branch. * `CURRENT_GIT_HASH` - Current Git hash. -_Configuration_ +##### Configuration Environment Variables The `CIENV_VARIABLES*` variables below are all derived from loading `.ciEnvironment.variables` JSON path from a project metadata file (if one exists) using `jq`. @@ -145,7 +154,7 @@ The `CIENV_VARIABLES*` variables below are all derived from loading `.ciEnvironm * `CIENV_VARIABLES_REQUIRED` - Array of project-specific CI environment variable names which are marked required (by their .required JSON path property). * `CIENV_VARIABLES_SECRET` - Array of project-specific CI environment variable names which ARE marked secret (by their .secret JSON path property). -_Conventional Output_ +##### Conventional Output Environment Variables * `BUILD_DOCS="${BUILD_ROOT}/docs"` - Project distributable documentation which would accompany packaged build output. * `BUILD_PACKAGED_DIST="${BUILD_ROOT}/dist"` - Project packaged build output. E.g., .NET NuGet packages, zip archives, AWS CDK cloud assemblies. @@ -154,7 +163,7 @@ _Conventional Output_ #### Initialization Workflow -1. Initialize convention-based CI enviroment variables. +1. Initialize convention-based CI environment variables. 2. Attempt to load project metadata by convention. * Populates `PROJECT_NAME`, `PROJECT_TITLE`, and `PROJECT_VERSION` from JSON file. From "name", "title", and "version" properties, respectively. * Default location: `PROJECT_ROOT/project-metadata.json` diff --git a/src/lib/ci/bash/actions/env.sh b/src/lib/ci/bash/actions/env.sh index a9f17cc..99f6dab 100755 --- a/src/lib/ci/bash/actions/env.sh +++ b/src/lib/ci/bash/actions/env.sh @@ -24,6 +24,10 @@ set -o pipefail # Fail pipelines if any command errors, not just the last one. # Design note: This function's name follows the CI workflow pattern because it is expected to be executed in a # workflow entrypoint script. # +# Optional initialization environment overrides: +# PROJECT_ROOT - Project root directory. Default: $(pwd) +# PROJECT_METADATA - Project metadata JSON file. Default: ${PROJECT_ROOT}/project-metadata.json | ${PROJECT_ROOT}/package.json +# # Expected environment available to all CI actions, after ci-env-init is executed: # - Contextual - # PROJECT_NAME - Project name. By convention this should be in lower kebab case. I.e., multi-word-project-name. This will be used to pattern conventional output paths, e.g., as part of a zip archive file name. @@ -46,7 +50,7 @@ set -o pipefail # Fail pipelines if any command errors, not just the last one. # BUILD_UNPACKAGED_DIST="${BUILD_ROOT}/app" - Project unpackaged build output. E.g., processed output which might be further packaged or compressed before distribution. E.g., .NET DLLs, Java class files. # # Workflow: -# 1 - Initialize convention-based CI enviroment variables. +# 1 - Initialize convention-based CI environment variables. # 2 - Attempt to load project metadata by convention. # Populates PROJECT_NAME, PROJECT_TITLE, and PROJECT_VERSION from JSON file. From "name", "title", and "version" properties, respectively. # Default location: PROJECT_ROOT/project-metadata.json @@ -76,6 +80,20 @@ function ci-env-init() { fi } + #---- + # Find first file which exists. + #---- + function __findFirstExistsFile() { + for fileName in "${@}"; do + if [[ -f "${fileName}" ]]; then + echo "${fileName}" + return 0 + fi + done + + return 1 + } + #---- # Tries to source a project environment file. #---- @@ -215,13 +233,15 @@ function ci-env-init() { fi } - __loadMetadataFromFile "${PROJECT_ROOT}/project-metadata.json" || - __loadMetadataFromFile "${PROJECT_ROOT}/.project-metadata.json" || - __loadMetadataFromFile "${PROJECT_ROOT}/ci/project-metadata.json" || - __loadMetadataFromFile "${PROJECT_ROOT}/ci/.project-metadata.json" || - __loadMetadataFromFile "${PROJECT_ROOT}/package.json" || - __loadMetadataFromFile "${PROJECT_ROOT}/src/package.json" || - return 0 + METADATA_FILE=$( + __findFirstExistsFile "${PROJECT_ROOT}/project-metadata.json" \ + "${PROJECT_ROOT}/.project-metadata.json" \ + "${PROJECT_ROOT}/ci/project-metadata.json" \ + "${PROJECT_ROOT}/ci/.project-metadata.json" \ + "${PROJECT_ROOT}/package.json" \ + "${PROJECT_ROOT}/src/package.json" + ) + __loadMetadataFromFile "${PROJECT_METADATA:-${METADATA_FILE}}" || return 0 } #----