Caution
This project has been superseded (and all of its useful bits subsumed) by @-xun/pipeline.
This project contains the collection of component actions powering the CI/CD pipeline that undergirds Projector-based projects. For more details on the pipeline's design, such as managing per-repository and cross-repository pipeline configurations, see ARCHITECTURE.md.
The following component actions can be imported as libraries via Node or invoked directly in your workflows:
audit-runtime
Unprivileged. Audits a project for security vulnerabilities. Currently, all
auditing is handled by npm audit.
Uses metadata-collect under the hood.
cleanup-npm
Privileged. Cleans up package metadata (e.g. pruning unused dist-tags) after
branch deletion.
Uses metadata-collect under the hood.
lint
Unprivileged. Lints project source via npm run lint.
Uses metadata-collect under the hood.
metadata-collect
Unprivileged. Checks out and configures the repository, installs and configures
Node, collects metadata, and uploads it as an artifact for use by various other component
actions. Must run only in unprivileged contexts.
It is usually not necessary to invoke this component action manually in workflows that invoke other component actions; this is because the other actions invoke this action internally. When invoked internally by another component action, any options passed to the invoking action will also be recognized by this action, even if the invoking action doesn't recognize any options by itself.
metadata-download
Unprivileged. Functionally equivalent to metadata-collect, except the metadata
is downloaded via an artifact created by metadata-collect. Can be used in both
privileged and unprivileged workflows.
It is usually not necessary to invoke this component action manually in workflows that invoke other component actions; this is because the other actions invoke this action internally. When invoked internally by another component action, any options passed to the invoking action will also be recognized by this action, even if the invoking action doesn't recognize any options by itself.
smart-deploy
Privileged. Uploads code coverage data if available, verifies actor permissions,
and checks for Projector template updates. Uses metadata-download under the
hood.
If a Projector template update is available, a new PR will be generated. If the pipeline was triggered by a PR event, an attempt will be made to auto-merge that PR before generating and submitting the new PR. Regardless, the current pipeline run will be aborted and a superseding pipeline run will be triggered by the new PR.
Otherwise, if the pipeline run was not triggered by a PR event, semantic-release
and related scripts are executed next, potentially resulting in package releases
and/or software deployments. If instead the pipeline was triggered by a PR
event, the PR will be auto-merged if eligible (see metadata-collect). Certain
failing merges will be automatically re-attempted using configurable exponential
back-off.
test-integration-client
Unprivileged. Runs all bespoke integration tests via npm run test-integration-client.
Uses metadata-collect under the hood.
test-integration-externals
Unprivileged. Runs all integration tests specific to project externals via
npm run test-integration-externals.
Uses metadata-collect under the hood.
test-integration-node
Unprivileged. Runs all Node-specific integration tests via npm run test-integration-node.
Uses metadata-collect under the hood.
test-integration-webpack
Unprivileged. Runs all Webpack-specific integration tests via npm run test-integration-webpack.
Uses metadata-collect under the hood.
test-unit-then-build
Unprivileged. Runs all unit tests and collects coverage data via npm run test-unit,
builds distributables via npm run build, and uploads the working tree as an artifact
for use by smart-deploy.
Uses metadata-collect under the hood.
verify-release
Unprivileged. Performs post-release package verification, e.g. ensure npm install
and related scripts function without errors. This action is best invoked several
minutes after a release has occurred so that release channels have a chance to
update their caches.
Uses metadata-download under the hood.
Each component action is directly invocable through a unified Actions interface.
Component actions are either privileged, where they require repository secrets
and GitHub write tokens (e.g. workflow_run), or unprivileged, where they
must not have access to secrets or write tokens (e.g. pull_request). It
is a major security vulnerability to invoke unprivileged component actions on
untrusted code outside properly sandboxed workflows.
UNPRIVILEGED ACTION
Example:
uses: xunnamius/[email protected]
with:
action: audit-runtimeThis component action does not recognize any options.
This component action has no outputs.
PRIVILEGED ACTION
This component action uses cached ~/npm data if available.
Example:
uses: xunnamius/[email protected]
with:
action: cleanup-npm
options: >
{
"npm-token": "your-npm-token-here"
}This action accepts an options JSON string input with the following properties
and constraints:
| Name | Type | Default | Description |
|---|---|---|---|
npm-token |
string |
(none) | [REQUIRED] An npm access token with read-write access to the appropriate package(s). |
See also: configuring the pipeline.
This component action has no outputs.
UNPRIVILEGED ACTION
This component action uses cached ~/npm data if available.
Example:
uses: xunnamius/[email protected]
with:
action: lintThis component action does not recognize any options.
This component action has no outputs.
UNPRIVILEGED ACTION
This component action uses cached ~/npm data if available and uploads the
collected metadata as an artifact with key
metadata-${{ runner.os }}-${{ github.sha }}.
Example:
uses: xunnamius/[email protected]
with:
action: metadata-collect
options: >
{
"github-token": "your-github-pat-here",
"upload-artifact": true,
"repository": {
"repositoryName": 'some-other-repo'
},
"node": false
}This action accepts an options JSON string input with the following properties
and constraints:
| Name | Type | Default | Description |
|---|---|---|---|
github-token |
string |
(none) | [REQUIRED] A GitHub access token with read access to the appropriate repository or repositories. ${{ github.token }} is usually the right value for this option. |
npm-token |
string |
(none) | An npm access token with read-write access to the appropriate package(s). |
issue-all-warnings |
boolean |
false |
If true, warnings that are usually hidden, like the pipeline debug warning, will be issued. This should only be enabled once per workflow file for aesthetic reasons. |
upload-artifact |
boolean |
false |
If true, a metadata artifact will be uploaded. This artifact can then be downloaded in the GitHub Actions UI or used by the metadata-collect component action. |
repository |
boolean | Partial<CloneOptions> |
true |
If truthy, the runtime repository's working tree will be checked out into the current working directory. If repository is a CloneOptions-like object, it is used as configuration. See also: configuring the pipeline. |
node |
boolean | Partial<NodeOptions> |
true |
If truthy, node will be downloaded and installed into the runtime and PATH. If node is a NodeOptions-like object, it is used as configuration. See also: configuring the pipeline. |
See also: configuring the pipeline.
See action.yml for possible outputs of this component action.
UNPRIVILEGED ACTION (but can be run in privileged workflows safely)
This component action uses cached ~/npm data if available and can download
collected metadata artifacts.
Example:
uses: xunnamius/[email protected]
with:
action: metadata-download
options: >
{
"github-token": "your-github-pat-here"
}This action accepts an options JSON string input with the following properties
and constraints:
| Name | Type | Default | Description |
|---|---|---|---|
github-token |
string |
(none) | [REQUIRED] A GitHub access token with read access to the appropriate repository or repositories. ${{ github.token }} is usually the right value for this option. |
npm-token |
string |
(none) | An npm access token with read-write access to the appropriate package(s). |
reissue-warnings |
boolean |
false |
If true, most pipeline warnings triggered by the downloaded metadata will be reissued. These warnings are always reported by the metadata-collect component action already, usually making reissuing the warnings redundant. |
repository |
boolean | Partial<CloneOptions> |
true |
If truthy, the runtime repository will be installed checked out into the current working directory. If repository is a CloneOptions-like object, it is used as configuration. See also: configuring the pipeline. |
node |
boolean | Partial<NodeOptions> |
true |
If truthy, node will be downloaded and installed into the runtime and PATH. If node is a NodeOptions-like object, it is used as configuration. See also: configuring the pipeline. |
See also: configuring the pipeline.
See action.yml for possible outputs of this component action.
PRIVILEGED ACTION
This component action requires both metadata and build artifacts to be
available, the former uploaded by metadata-collect with artifact key
build-${{ runner.os }}-${{ github.sha }} and the latter by
test-unit-then-build with artifact key
metadata-${{ runner.os }}-${{ github.sha }}.
This component action also downloads a remote package.json file during
operation. This file is used to safely install npm dependencies in privileged
environments. The permanent URI for this download is:
https://github.com/xunnamius/projector-pipeline/raw/main/dist/privileged/package.json
Example:
uses: xunnamius/[email protected]
with:
action: smart-deploy
options: >
{
"github-token": "your-github-pat-here",
"npm-token": "your-npm-token-here",
"gpg-private-key-armored": "your-private-key-here",
"gpg-passphrase": "your-passphrase-here"
}This action accepts an options JSON string input with the following properties
and constraints:
| Name | Type | Default | Description |
|---|---|---|---|
github-token |
string |
(none) | [REQUIRED] A GitHub access token with read-write access to the appropriate repository or repositories. |
npm-token |
string |
(none) | [REQUIRED] An npm access token with read-write access to the appropriate package(s). |
codecov-token |
string |
(none) | A Codecov token corresponding to the target repository. Not necessary and should be omitted for public repositories. |
gpg-pk-armored |
string |
(none) | [REQUIRED] The armored GPG private key used for git signing purposes. This key must correspond to committer.email. |
gpg-passphrase |
string |
(none) | [REQUIRED] The passphrase that unlocks gpg-pk-armored. |
This component action always passes
{ repository: { ...customRepoOptions, checkoutRef: false }} to
metadata-download. This means, regardless of any custom repository
settings (customRepoOptions above) provided, checkoutRef will always be
false.
See also: configuring the pipeline.
This component action has no outputs.
UNPRIVILEGED ACTION
This component action uses cached ~/npm data if available.
Example:
uses: xunnamius/[email protected]
with:
action: test-integration-clientThis component action does not recognize any options.
This component action has no outputs.
UNPRIVILEGED ACTION
This component action uses cached ~/npm data if available.
Example:
uses: xunnamius/[email protected]
with:
action: test-integration-externalsThis component action does not recognize any options.
This component action has no outputs.
UNPRIVILEGED ACTION
This component action uses cached ~/npm data if available.
Example:
uses: xunnamius/[email protected]
with:
action: test-integration-nodeThis component action does not recognize any options.
This component action has no outputs.
UNPRIVILEGED ACTION
This component action uses cached ~/npm data if available.
Example:
uses: xunnamius/[email protected]
with:
action: test-integration-webpackThis component action does not recognize any options.
This component action has no outputs.
UNPRIVILEGED ACTION
This component action uses cached ~/npm data if available and uploads the
working tree as an artifact with key build-${{ runner.os }}-${{ github.sha }}.
Example:
uses: xunnamius/[email protected]
with:
action: test-unit-then-buildThis component action does not recognize any options.
This component action has no outputs.
UNPRIVILEGED ACTION
This component action uses cached ~/npm data if available.
Example:
uses: xunnamius/[email protected]
with:
action: verify-releaseThis component action does not recognize any options.
This component action has no outputs.
Each component action can also be imported and run locally via unified npm package.
Note: npm versions >=7 may need
npm install --legacy-peer-depsuntil upstream peer dependency problems are resolved.
npm install @xunnamius/projector-pipeline[additional details]
Note: you probably don't need to read through this! This information is primarily useful for those attempting to bundle this package or for people who have an opinion on ESM versus CJS.
This is a dual CJS2/ES module package. That means this package exposes both CJS2 and ESM entry points.
Loading this package via require(...) will cause Node and Webpack to use the
CJS2 bundle entry point, disable tree shaking in Webpack
4, and lead to larger bundles in Webpack 5. Alternatively, loading this package
via import { ... } from ... or import(...) will cause Node to use the ESM
entry point in versions that support it, as will Webpack.
Using the import syntax is the modern, preferred choice.
For backwards compatibility with Webpack 4 (compat with Webpack 4 is not
guaranteed!) and Node versions < 14, package.json retains the
module key, which points to the ESM entry point, and the
main key, which points to the CJS2 entry point explicitly
(using the .js file extension). For Webpack 5 and Node versions >= 14,
package.json includes the exports key,
which points to both entry points explicitly.
Though package.json includes
{ "type": "commonjs"}, note that the ESM entry points are ES
module (.mjs) files. package.json also includes the
sideEffects key, which is false for optimal tree
shaking, and the types key, which points to a TypeScript
declarations file.
Additionally, this package does not maintain shared state and so does not exhibit the dual package hazard. However, setting global configuration may not actually be "globally" recognized by third-party code importing this package.
import { invokeComponentAction } from '@xunnamius/projector-pipeline';
const result = await invokeComponentAction('metadata-collect', {
githubToken: 'my-github-pat',
uploadArtifact: true
});
console.log(result.outputs['should-skip-ci']); // Prints a booleanFurther documentation for using the npm package can be found under
docs/. See ARCHITECTURE.md and
CONTRIBUTING.md for more details on the pipeline.
New issues and pull requests are always welcome and greatly appreciated! 🤩 Just as well, you can star 🌟 this project to let me know you found it useful! ✊🏿 Thank you!
See CONTRIBUTING.md and SUPPORT.md for more information.