├── .circleci ├── README.md ├── config.yml └── test-deploy.yml ├── .github ├── CODEOWNERS ├── ISSUE_TEMPLATE │ ├── BUG.md │ ├── FEATURE_REQUEST.md │ └── config.yml └── PULL_REQUEST_TEMPLATE │ └── PULL_REQUEST.md ├── .gitignore ├── .yamllint ├── CHANGELOG.md ├── LICENSE ├── README.md └── src ├── @orb.yml ├── README.md ├── commands ├── README.md ├── generate-config.yml └── set-parameters.yml ├── examples ├── README.md └── path_filtering.yml ├── executors ├── README.md └── default.yml ├── jobs ├── README.md └── filter.yml ├── scripts ├── README.md ├── create-parameters.sh └── generate-config.sh └── tests └── README.md /.circleci/README.md: -------------------------------------------------------------------------------- 1 | # Orb Development Pipeline 2 | 3 | This configuration file uses [orb-tools orb]() version 10 to automatically _pack_, _test_, and _publish_ CircleCI orbs using this project structure. View the comments within the config file for a full break down 4 | 5 | ## Overview: 6 | 7 | **Imported Orbs** 8 | 9 | Both orb-tools and a development version of your orb will be imported into the config. On the first run, a `dev:alpha` development tag _must_ exist on your orb, but will be handled automatically from there on. 10 | 11 | **Jobs** 12 | 13 | In the _jobs_ key, you will define _integration tests_. These jobs will utilize the functionality of your orb at run-time and attempt to validate their usage with live examples. Integration tests can be an excellent way of determining issues with parameters and run-time execution. 14 | 15 | ### Workflows 16 | 17 | There are two workflows which automate the pack, test, and publishing process. 18 | 19 | **test-pack** 20 | 21 | This is the first of the two workflows run. This workflow is responsible for any testing or prepping prior to integration tests. This is where linting occurs, shellchecking, BATS tests, or anything else that can be be tested without the need for further credentials. 22 | 23 | This Workflow will be placed on _hold_ prior to publishing a new development version of the orb (based on this commit), as this step requires access to specific publishing credentials. 24 | 25 | This allows users to fork the orb repository and begin the pipeline, while the code-owners review that the code is safe to test in an environment where publishing keys will be present. 26 | 27 | Once approved, the development version of the orb will publish and the _trigger-integration-tests-workflow_ job will run, kicking off the next workflow 28 | 29 | **integration-test_deploy** 30 | 31 | The second and final workflow is manually triggered by the _trigger-integration-tests-workflow_ job. In this run, the development version of the orb that was just published will be imported, and the integration tests will run. 32 | 33 | When running on the `master` branch (after merging to `master`), the workflow will additionally publish your new production orb. -------------------------------------------------------------------------------- /.circleci/config.yml: -------------------------------------------------------------------------------- 1 | version: 2.1 2 | 3 | setup: true 4 | orbs: 5 | orb-tools: circleci/orb-tools@11.6.1 6 | shellcheck: circleci/shellcheck@3.4 7 | 8 | filters: &filters 9 | tags: 10 | only: /.+/ 11 | 12 | workflows: 13 | lint-pack: 14 | jobs: 15 | - orb-tools/lint: 16 | filters: *filters 17 | - orb-tools/pack: 18 | filters: *filters 19 | - orb-tools/review: 20 | filters: *filters 21 | - shellcheck/check: 22 | filters: *filters 23 | - orb-tools/publish: 24 | orb-name: circleci/path-filtering 25 | vcs-type: << pipeline.project.type >> 26 | requires: 27 | [orb-tools/lint, orb-tools/review, orb-tools/pack, shellcheck/check] 28 | context: orb-publisher 29 | filters: *filters 30 | - orb-tools/continue: 31 | pipeline-number: << pipeline.number >> 32 | vcs-type: << pipeline.project.type >> 33 | requires: [orb-tools/publish] 34 | filters: *filters 35 | -------------------------------------------------------------------------------- /.circleci/test-deploy.yml: -------------------------------------------------------------------------------- 1 | version: 2.1 2 | orbs: 3 | path-filtering: circleci/path-filtering@dev:<> 4 | orb-tools: circleci/orb-tools@11.6.1 5 | 6 | filters: &filters 7 | tags: 8 | only: /.+/ 9 | 10 | executors: 11 | docker-base: 12 | docker: 13 | - image: cimg/base:stable 14 | macos: 15 | macos: 16 | xcode: 16.2.0 17 | arm: 18 | machine: 19 | image: ubuntu-2404:current 20 | resource_class: arm.medium 21 | linuxvm: 22 | machine: 23 | image: ubuntu-2404:current 24 | jobs: 25 | set-parameters-same-base: 26 | parameters: 27 | same-base-run: 28 | type: boolean 29 | docker: 30 | - image: cimg/base:current 31 | steps: 32 | - checkout 33 | - run: echo 'export BASE_REVISION=$(git rev-parse --abbrev-ref HEAD)' >> $BASH_ENV 34 | - path-filtering/set-parameters: 35 | mapping: | 36 | src/.* foo bar 37 | base-revision: $BASE_REVISION 38 | same-base-run: <> 39 | set-parameters-test: 40 | docker: 41 | - image: cimg/base:current 42 | steps: 43 | - checkout 44 | - path-filtering/set-parameters: 45 | mapping: | 46 | src/.* test-changes true 47 | src/examples/.* string-example "value" 48 | - path-filtering/set-parameters: 49 | config-path: ".circleci/test-deploy.yml" 50 | mapping: | 51 | src/commands/.* test-commands true .circleci/config.yml 52 | src/examples/.* test-examples true .circleci/test-deploy.yml 53 | src/jobs/.* test-jobs true .circleci/config.yml 54 | src/tests/.* test-tests true .circleci/test-deploy.yml 55 | 56 | - path-filtering/generate-config: 57 | config-list-path: /tmp/filtered-config-list 58 | generated-config-path: "/tmp/generated-config.yml" 59 | 60 | 61 | 62 | workflows: 63 | test-deploy: 64 | jobs: 65 | - path-filtering/filter: 66 | name: filter-macos 67 | debug: true 68 | base-revision: main 69 | config-path: .circleci/config.yml 70 | executor: macos 71 | resource_class: macos.m1.medium.gen1 72 | mapping: | 73 | src/.* build-code true 74 | - path-filtering/filter: 75 | name: filter-arm 76 | debug: true 77 | base-revision: main 78 | config-path: .circleci/config.yml 79 | executor: arm 80 | resource_class: arm.medium 81 | mapping: | 82 | src/.* build-code true 83 | - path-filtering/filter: 84 | debug: true 85 | base-revision: main 86 | config-path: .circleci/config.yml 87 | mapping: | 88 | src/.* build-code true 89 | matrix: 90 | alias: filter 91 | parameters: 92 | executor: [path-filtering/default, docker-base, linuxvm] 93 | - set-parameters-same-base: 94 | matrix: 95 | alias: set-parameters-same-base 96 | parameters: 97 | same-base-run: [true, false] 98 | filters: *filters 99 | - set-parameters-test: 100 | filters: *filters 101 | - orb-tools/pack: 102 | filters: *filters 103 | - orb-tools/publish: 104 | orb-name: circleci/path-filtering 105 | vcs-type: << pipeline.project.type >> 106 | pub-type: production 107 | requires: 108 | - orb-tools/pack 109 | - filter 110 | - filter-macos 111 | - filter-arm 112 | - set-parameters-test 113 | - set-parameters-same-base 114 | context: orb-publisher 115 | filters: 116 | branches: 117 | ignore: /.*/ 118 | tags: 119 | only: /^v[0-9]+\.[0-9]+\.[0-9]+$/ 120 | -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @CircleCI-Public/orb-publishers 2 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/BUG.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: "\U0001F41E Bug report" 3 | about: Report any bugs encountered while using this orb. 4 | title: '' 5 | labels: bug 6 | assignees: '' 7 | 8 | --- 9 | 10 | ## Orb version: 11 | 12 | 19 | 20 | ## What happened: 21 | 22 | 26 | 27 | ## Expected behavior: 28 | 29 | 30 | 31 | ## Additional Information: 32 | 33 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: "\U0001F680 Feature Request" 3 | about: Propose changes to the orb. 4 | title: '' 5 | labels: feature_request 6 | assignees: '' 7 | --- 8 | 9 | ## Describe Request: 10 | 11 | ## Examples: 12 | 13 | ## Supporting Documentation Links: 14 | 15 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE/PULL_REQUEST.md: -------------------------------------------------------------------------------- 1 | 2 | **SEMVER Update Type:** 3 | - [ ] Major 4 | - [ ] Minor 5 | - [ ] Patch 6 | 7 | ## Description: 8 | 9 | 13 | 14 | ## Motivation: 15 | 16 | 19 | 20 | **Closes Issues:** 21 | - ISSUE URL 22 | 23 | ## Checklist: 24 | 25 | 30 | 31 | - [ ] All new jobs, commands, executors, parameters have descriptions. 32 | - [ ] Usage Example version numbers have been updated. 33 | - [ ] Changelog has been updated. -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # orb.yml is "packed" from source, and not published directly from the repository. 2 | orb.yml -------------------------------------------------------------------------------- /.yamllint: -------------------------------------------------------------------------------- 1 | extends: relaxed 2 | 3 | rules: 4 | line-length: 5 | max: 200 6 | allow-non-breakable-inline-mappings: true 7 | 8 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | All notable changes to this project will be documented in this file. 3 | 4 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 5 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). 6 | 7 | ## [Unreleased] 8 | - Current development changes [ to be moved to release ] 9 | 10 | ## [1.0.0] - YYYY-MM-DD 11 | ### Added 12 | - Initial Release 13 | ### Changed 14 | - Initial Release 15 | ### Removed 16 | - Initial Release 17 | 18 | 19 | [1.0.0]: GITHUB TAG URL 20 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2021 CircleCI-Public 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Path Filtering Orb 2 | [![CircleCI Build Status](https://circleci.com/gh/CircleCI-Public/path-filtering-orb.svg?style=shield "CircleCI Build Status")](https://circleci.com/gh/CircleCI-Public/path-filtering-orb) [![CircleCI Orb Version](https://badges.circleci.com/orbs/circleci/path-filtering.svg)](https://circleci.com/developer/orbs/orb/circleci/path-filtering) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/circleci-public/path-filtering-orb/master/LICENSE) [![CircleCI Community](https://img.shields.io/badge/community-CircleCI%20Discuss-343434.svg)](https://discuss.circleci.com/c/ecosystem/orbs) 3 | 4 | A starter template for orb projects. Build, test, and publish orbs automatically on CircleCI with [Orb-Tools](https://circleci.com/orbs/registry/orb/circleci/orb-tools). 5 | 6 | Additional READMEs are available in each directory. 7 | 8 | **Meta**: This repository is open for contributions! Feel free to open a pull request with your changes. Due to the nature of this repository, it is not built on CircleCI. The Resources and How to Contribute sections relate to an orb created with this template, rather than the template itself. 9 | 10 | ## Resources 11 | 12 | [Dynamic Config](https://circleci.com/docs/2.0/dynamic-config) - CircleCI functionality that the path-filtering-orb contributes to 13 | 14 | [Setup Workflows Documentation](https://github.com/CircleCI-Public/api-preview-docs/blob/master/docs/setup-workflows.md#concepts) - Doc explaining a special type of workflow used in dynamic config 15 | 16 | [CircleCI Orb Registry Page](https://circleci.com/developer/orbs/orb/circleci/path-filtering) - The official registry page of this orb for all versions, executors, commands, and jobs described. 17 | 18 | [CircleCI Orb Docs](https://circleci.com/docs/2.0/orb-intro/#section=configuration) - Docs for using, creating, and publishing CircleCI Orbs. 19 | 20 | ### How to Contribute 21 | 22 | We welcome [issues](https://github.com/CircleCI-Public/path-filtering-orb/issues) to and [pull requests](https://github.com/CircleCI-Public/path-filtering-orb/pulls) against this repository! 23 | 24 | ### How to Publish An Update 25 | 1. Merge pull requests with desired changes to the main branch. 26 | - For the best experience, squash-and-merge and use [Conventional Commit Messages](https://conventionalcommits.org/). 27 | 2. Find the current version of the orb. 28 | - You can run `circleci orb info circleci/path-filtering | grep "Latest"` to see the current version. 29 | 3. Create a [new Release](https://github.com/CircleCI-Public/path-filtering-orb/releases/new) on GitHub. 30 | - Click "Choose a tag" and _create_ a new [semantically versioned](http://semver.org/) tag. (ex: v1.0.0) 31 | - We will have an opportunity to change this before we publish if needed after the next step. 32 | 4. Click _"+ Auto-generate release notes"_. 33 | - This will create a summary of all of the merged pull requests since the previous release. 34 | - If you have used _[Conventional Commit Messages](https://conventionalcommits.org/)_ it will be easy to determine what types of changes were made, allowing you to ensure the correct version tag is being published. 35 | 5. Now ensure the version tag selected is semantically accurate based on the changes included. 36 | 6. Click _"Publish Release"_. 37 | - This will push a new tag and trigger your publishing pipeline on CircleCI. 38 | -------------------------------------------------------------------------------- /src/@orb.yml: -------------------------------------------------------------------------------- 1 | version: 2.1 2 | 3 | description: > 4 | Continue a pipeline based on paths of changed files. 5 | This can be useful in a monorepo setup where one may want to trigger different workflows 6 | based on which module(s) in the repo has changed. 7 | This orb does not support server at this time. 8 | display: 9 | home_url: "https://circleci.com/docs/2.0/dynamic-config" 10 | source_url: "https://github.com/CircleCI-Public/path-filtering-orb" 11 | 12 | orbs: 13 | continuation: circleci/continuation@2.0.0 14 | jq: circleci/jq@3.0.2 15 | -------------------------------------------------------------------------------- /src/README.md: -------------------------------------------------------------------------------- 1 | # Orb Source 2 | 3 | Orbs are shipped as individual `orb.yml` files, however, to make development easier, it is possible to author an orb in _unpacked_ form, which can be _packed_ with the CircleCI CLI and published. 4 | 5 | The default `.circleci/config.yml` file contains the configuration code needed to automatically pack, test, and deploy and changes made to the contents of the orb source in this directory. 6 | 7 | ## @orb.yml 8 | 9 | This is the entry point for our orb "tree", which becomes our `orb.yml` file later. 10 | 11 | Within the `@orb.yml` we generally specify 4 configuration keys 12 | 13 | **Keys** 14 | 15 | 1. **version** 16 | Specify version 2.1 for orb-compatible configuration `version: 2.1` 17 | 2. **description** 18 | Give your orb a description. Shown within the CLI and orb registry 19 | 3. **display** 20 | Specify the `home_url` referencing documentation or product URL, and `source_url` linking to the orb's source repository. 21 | 4. **orbs** 22 | (optional) Some orbs may depend on other orbs. Import them here. 23 | 24 | ## See: 25 | - [Orb Author Intro](https://circleci.com/docs/2.0/orb-author-intro/#section=configuration) 26 | - [Reusable Configuration](https://circleci.com/docs/2.0/reusing-config) -------------------------------------------------------------------------------- /src/commands/README.md: -------------------------------------------------------------------------------- 1 | # Commands 2 | 3 | Easily add and author [Reusable Commands](https://circleci.com/docs/2.0/reusing-config/#authoring-reusable-commands) to the `src/commands` directory. 4 | 5 | Each _YAML_ file within this directory will be treated as an orb command, with a name which matches its filename. 6 | 7 | View the included _[greet.yml](./greet.yml)_ example. 8 | 9 | ```yaml 10 | description: > 11 | Replace this text with a description for this command. 12 | # What will this command do? 13 | # Descriptions should be short, simple, and clear. 14 | parameters: 15 | greeting: 16 | type: string 17 | default: "Hello" 18 | description: "Select a proper greeting" 19 | steps: 20 | - run: 21 | name: Hello World 22 | command: echo << parameters.greeting >> world 23 | ``` 24 | 25 | ## See: 26 | - [Orb Author Intro](https://circleci.com/docs/2.0/orb-author-intro/#section=configuration) 27 | - [How to author commands](https://circleci.com/docs/2.0/reusing-config/#authoring-reusable-commands) 28 | -------------------------------------------------------------------------------- /src/commands/generate-config.yml: -------------------------------------------------------------------------------- 1 | description: > 2 | Generate config file from the config list. 3 | parameters: 4 | config-list-path: 5 | type: string 6 | default: /tmp/filtered-config-list 7 | description: > 8 | A file path to append config paths. 9 | Each path in this file should be relative to the working directory. 10 | generated-config-path: 11 | type: string 12 | default: /tmp/generated-config.yml 13 | description: > 14 | A file path for the generated config file. 15 | steps: 16 | - run: 17 | environment: 18 | PARAM_CONFIG_LIST_PATH: <> 19 | PARAM_GENERATED_CONFIG_PATH: <> 20 | name: Generate config 21 | command: <> 22 | -------------------------------------------------------------------------------- /src/commands/set-parameters.yml: -------------------------------------------------------------------------------- 1 | description: > 2 | Generates a set of pipeline parameters from `mapping` at 3 | `output-path`. Python is required to run this command. 4 | 5 | parameters: 6 | base-revision: 7 | type: string 8 | default: "main" 9 | description: > 10 | The revision to compare the current one against for the purpose 11 | of determining changed files. 12 | mapping: 13 | type: string 14 | default: "" 15 | description: > 16 | Mapping of path regular expressions to pipeline parameters and 17 | values. One mapping per line, whitespace-delimited. If duplicate 18 | parameter keys are found, the last matching pattern will apply. 19 | exclude: 20 | type: string 21 | default: "" 22 | description: > 23 | List of paths to exclude from the mapping. One path per line. 24 | output-path: 25 | type: string 26 | default: "/tmp/pipeline-parameters.json" 27 | description: > 28 | Path to save the generated parameters to. 29 | config-path: 30 | type: string 31 | default: ".circleci/continue_config.yml" 32 | description: > 33 | The location of the config to continue the pipeline with, please note that this parameter 34 | will be ignored if the user passes the config file per mapping in the mapping parameter 35 | same-base-run: 36 | type: boolean 37 | default: true 38 | description: > 39 | This is value is used to know what to do when the base revision is the same as the current commit. 40 | When set to true, it will compare with the previous commit. 41 | When set to false, it will act as if not changes were done. 42 | steps: 43 | - jq/install 44 | - run: 45 | name: Set parameters 46 | environment: 47 | BASE_REVISION: << parameters.base-revision >> 48 | MAPPING: << parameters.mapping >> 49 | OUTPUT_PATH: << parameters.output-path >> 50 | CONFIG_PATH: << parameters.config-path >> 51 | EXCLUDE: <> 52 | SAME_BASE_RUN: <> 53 | command: <> 54 | -------------------------------------------------------------------------------- /src/examples/README.md: -------------------------------------------------------------------------------- 1 | # Usage Examples 2 | 3 | Easily author and add [Usage Examples](https://circleci.com/docs/2.0/orb-author/#providing-usage-examples-of-orbs) to the `src/examples` directory. 4 | 5 | Each _YAML_ file within this directory will be treated as an orb usage example, with a name which matches its filename. 6 | 7 | View the included _[example.yml](./example.yml)_ example. 8 | 9 | Usage examples should contain clear use-case based example configurations for using the orb. 10 | 11 | 12 | ## See: 13 | - [Providing Usage examples](https://circleci.com/docs/2.0/orb-author/#providing-usage-examples-of-orbs) -------------------------------------------------------------------------------- /src/examples/path_filtering.yml: -------------------------------------------------------------------------------- 1 | description: > 2 | Continue a pipeline from the setup phase with supplied configuration 3 | and pipeline parameters generated from the files changed. 4 | usage: 5 | version: 2.1 6 | setup: true 7 | orbs: 8 | path-filtering: circleci/path-filtering@0.1.7 9 | workflows: 10 | generate-config: 11 | jobs: 12 | - path-filtering/filter: 13 | base-revision: main 14 | config-path: .circleci/continue_config.yml 15 | mapping: | 16 | src/.* build-code true 17 | doc/.* build-docs true 18 | src/tests/.* string-parameter "value" 19 | - path-filtering/filter: 20 | base-revision: main 21 | # This config-path file will only be used to continue the Pipeline if none of the changes 22 | # satisfy the below mapping conditions. 23 | config-path: .circleci/continue_config.yml 24 | # Please note the two config files specified below cannot share the same job, workflow or command names. 25 | # This is due to the fact that we're merging those into one file behind the scenes. 26 | mapping: | 27 | src/.* build-code true .circleci/build-code-config.yml 28 | doc/.* build-docs true .circleci/build-docs-config.yml 29 | - path-filtering/filter: 30 | base-revision: main 31 | config-path: .circleci/continue-config.yml 32 | mapping: .circleci/mapping.conf 33 | - path-filtering/filter: 34 | base-revision: main 35 | exclude: | 36 | src/config.yml 37 | build/target/.* 38 | config-path: .circleci/continue_config.yml 39 | # There are four ways to pass a mapping line 40 | # Only path 41 | # Path and config file 42 | # Path and parameters 43 | # Path, parameters and config file 44 | mapping: | 45 | src/.* 46 | doc/.* .circleci/build-docs-config.yml 47 | tests/.* foo bar 48 | build/.* foo bar .circleci/build.yml 49 | -------------------------------------------------------------------------------- /src/executors/README.md: -------------------------------------------------------------------------------- 1 | # Executors 2 | 3 | Easily author and add [Parameterized Executors](https://circleci.com/docs/2.0/reusing-config/#executors) to the `src/executors` directory. 4 | 5 | Each _YAML_ file within this directory will be treated as an orb executor, with a name which matches its filename. 6 | 7 | Executors can be used to parameterize the same environment across many jobs. Orbs nor jobs _require_ executors, but may be helpful in some cases, such as: [parameterizing the Node version for a testing job so that matrix testing may be used](https://circleci.com/orbs/registry/orb/circleci/node#usage-run_matrix_testing). 8 | 9 | View the included _[hello.yml](./hello.yml)_ example. 10 | 11 | 12 | ```yaml 13 | description: > 14 | This is a sample executor using Docker and Node. 15 | docker: 16 | - image: 'cimg/node:<>' 17 | parameters: 18 | tag: 19 | default: lts 20 | description: > 21 | Pick a specific circleci/node image variant: 22 | https://hub.docker.com/r/cimg/node/tags 23 | type: string 24 | ``` 25 | 26 | ## See: 27 | - [Orb Author Intro](https://circleci.com/docs/2.0/orb-author-intro/#section=configuration) 28 | - [How To Author Executors](https://circleci.com/docs/2.0/reusing-config/#authoring-reusable-executors) 29 | - [Node Orb Executor](https://github.com/CircleCI-Public/node-orb/blob/master/src/executors/default.yml) -------------------------------------------------------------------------------- /src/executors/default.yml: -------------------------------------------------------------------------------- 1 | description: > 2 | This is a sample executor using Docker and Python. 3 | 4 | docker: 5 | - image: 'cimg/python:<>' 6 | 7 | parameters: 8 | tag: 9 | type: string 10 | default: "3.12" 11 | description: > 12 | Pick a specific cimg/python image variant: 13 | https://hub.docker.com/r/cimg/python/tags 14 | -------------------------------------------------------------------------------- /src/jobs/README.md: -------------------------------------------------------------------------------- 1 | # Jobs 2 | 3 | Easily author and add [Parameterized Jobs](https://circleci.com/docs/2.0/reusing-config/#authoring-parameterized-jobs) to the `src/jobs` directory. 4 | 5 | Each _YAML_ file within this directory will be treated as an orb job, with a name which matches its filename. 6 | 7 | Jobs may invoke orb commands and other steps to fully automate tasks with minimal user configuration. 8 | 9 | View the included _[hello.yml](./hello.yml)_ example. 10 | 11 | 12 | ```yaml 13 | # What will this job do? 14 | # Descriptions should be short, simple, and clear. 15 | Sample description 16 | executor: default 17 | parameters: 18 | greeting: 19 | type: string 20 | default: "Hello" 21 | description: "Select a proper greeting" 22 | steps: 23 | - greet: 24 | greeting: << parameters.greeting >> 25 | ``` 26 | 27 | ## See: 28 | - [Orb Author Intro](https://circleci.com/docs/2.0/orb-author-intro/#section=configuration) 29 | - [How To Author Commands](https://circleci.com/docs/2.0/reusing-config/#authoring-parameterized-jobs) 30 | - [Node Orb "test" Job](https://github.com/CircleCI-Public/node-orb/blob/master/src/jobs/test.yml) -------------------------------------------------------------------------------- /src/jobs/filter.yml: -------------------------------------------------------------------------------- 1 | description: > 2 | Continues a pipeline in the `setup` state based with static config 3 | and a set of pipeline parameters based on the changes in this push. 4 | 5 | The mapping should be a set of items like so: 6 | 7 | Multiple mappings can be supplied on separate lines. 8 | If the regular expression matches any file changed between HEAD and 9 | the base revision, the pipeline parameter will be set to the 10 | supplied value for the setup workflow continuation. This way the 11 | continuation config can be filtered to only perform relevant tasks. 12 | 13 | executor: <> 14 | 15 | resource_class: << parameters.resource_class >> 16 | 17 | parameters: 18 | base-revision: 19 | type: string 20 | default: "main" 21 | description: > 22 | The revision to compare the current one against for the purpose 23 | of determining changed files. 24 | mapping: 25 | type: string 26 | default: "" 27 | description: > 28 | Mapping of path regular expressions to pipeline parameters and 29 | values. If the value is a file, then it will be loaded from the disk. 30 | One mapping per line, whitespace-delimited. 31 | config-path: 32 | type: string 33 | default: ".circleci/continue_config.yml" 34 | description: > 35 | The location of the config to continue the pipeline with, please note that this parameter 36 | will be ignored if the user passes the config file per mapping in the mapping parameter 37 | circleci_domain: 38 | type: string 39 | description: "The domain of the CircleCI installation - defaults to circleci.com. (Only necessary for CircleCI Server users)" 40 | default: "circleci.com" 41 | workspace_path: 42 | type: string 43 | description: "Path to attach the workspace to" 44 | default: "" 45 | output-path: 46 | type: string 47 | default: "/tmp/pipeline-parameters.json" 48 | description: > 49 | Path to save the generated parameters to. 50 | resource_class: 51 | type: string 52 | description: "Resource class to use" 53 | default: "small" 54 | executor: 55 | type: executor 56 | description: "Executor where to run this job" 57 | default: default 58 | circleci_ip_ranges: 59 | description: Enables jobs to go through a set of well-defined IP address ranges. 60 | type: boolean 61 | default: false 62 | checkout: 63 | type: boolean 64 | description: "Whether to run an optional checkout step before continuing" 65 | default: true 66 | exclude: 67 | type: string 68 | default: "" 69 | description: > 70 | List of paths to exclude from the mapping. One path per line. 71 | same-base-run: 72 | type: boolean 73 | default: true 74 | description: > 75 | This is value is used to know what to do when the base revision is the same as the current commit. 76 | When set to true, it will compare with the previous commit. 77 | When set to false, it will act as if not changes were done. 78 | debug: 79 | type: boolean 80 | default: false 81 | description: > 82 | This mode is use for testing purposes. Defaults to False 83 | When this is set to True, the parameters and the config will be generated, but the continuation won't be called. 84 | parameter_for_files_changed: 85 | type: string 86 | default: "" 87 | description: > 88 | If you want to get the list of files changed in the dynamic config, this value is the name of the parameter containing those files in there. 89 | Defaults to empty string. 90 | Set to empty string if you don't want the parameter. 91 | circleci_ip_ranges: << parameters.circleci_ip_ranges >> 92 | 93 | steps: 94 | - when: 95 | condition: 96 | equal: [ true, << parameters.checkout >> ] 97 | steps: 98 | - checkout 99 | - when: 100 | condition: 101 | not: 102 | equal: ["", << parameters.workspace_path >>] 103 | steps: 104 | - attach_workspace: 105 | at: << parameters.workspace_path >> 106 | - set-parameters: 107 | base-revision: << parameters.base-revision >> 108 | mapping: << parameters.mapping >> 109 | output-path: << parameters.output-path >> 110 | config-path: << parameters.config-path >> 111 | exclude: <> 112 | same-base-run: <> 113 | - generate-config: 114 | config-list-path: /tmp/filtered-config-list 115 | generated-config-path: "/tmp/generated-config.yml" 116 | 117 | - when: 118 | condition: 119 | equal: [ false, <> ] 120 | steps: 121 | - continuation/continue: 122 | configuration_path: "/tmp/generated-config.yml" 123 | files_changed: /tmp/files-changed-list 124 | parameter_for_files_changed: <> 125 | parameters: << parameters.output-path >> 126 | circleci_domain: << parameters.circleci_domain >> 127 | -------------------------------------------------------------------------------- /src/scripts/README.md: -------------------------------------------------------------------------------- 1 | # scripts/ 2 | 3 | This is where any scripts you wish to include in your orb can be kept. This is encouraged to ensure your orb can have all aspects tested, and is easier to author, since we sacrifice most features an editor offers when editing scripts as text in YAML. 4 | 5 | As a part of keeping things separate, it is encouraged to use environment variables to pass through parameters, rather than using the `<< parameter. >>` syntax that CircleCI offers. 6 | 7 | # Including Scripts 8 | 9 | Utilizing the `circleci orb pack` CLI command, it is possible to import files (such as _shell scripts_), using the `<>` syntax in place of any config key's value. 10 | 11 | ```yaml 12 | # commands/greet.yml 13 | description: > 14 | This command echos "Hello World" using file inclusion. 15 | parameters: 16 | to: 17 | type: string 18 | default: "World" 19 | description: "Hello to who?" 20 | steps: 21 | - run: 22 | environment: 23 | PARAM_TO: < 24 | name: Hello < 25 | command: <> 26 | 27 | ``` 28 | 29 | ```shell 30 | # scripts/greet.sh 31 | Greet() { 32 | echo Hello ${PARAM_TO} 33 | } 34 | 35 | # Will not run if sourced from another script. This is done so this script may be tested. 36 | # View src/tests for more information. 37 | if [[ "$_" == "$0" ]]; then 38 | Greet 39 | fi 40 | ``` 41 | -------------------------------------------------------------------------------- /src/scripts/create-parameters.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | MAPPING="$(echo "$MAPPING" | circleci env subst)" 3 | EXCLUDE="$(echo "$EXCLUDE" | circleci env subst)" 4 | OUTPUT_PATH="$(echo "$OUTPUT_PATH" | circleci env subst)" 5 | CONFIG_PATH="$(echo "$CONFIG_PATH" | circleci env subst)" 6 | BASE_REVISION="$(echo "$BASE_REVISION" | circleci env subst)" 7 | SAME_BASE_RUN="$(echo "$SAME_BASE_RUN" | circleci env subst)" 8 | 9 | filtered_config_list_file="/tmp/filtered-config-list" 10 | files_changed_file="/tmp/files-changed-list" 11 | git checkout "$BASE_REVISION" 12 | git checkout "$CIRCLE_SHA1" 13 | MERGE_BASE=$(git merge-base "$BASE_REVISION" "$CIRCLE_SHA1") 14 | 15 | function is_mapping_line() { 16 | local line="$1" 17 | local trimmed 18 | trimmed=$(echo "$line" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//') 19 | if [[ -z "$trimmed" || "$trimmed" == \#* ]]; then 20 | return 1 21 | else 22 | return 0 23 | fi 24 | } 25 | 26 | function write_mappings() { 27 | local output_path="$1" 28 | shift 29 | { 30 | echo -n "{" 31 | local first=true 32 | for i in "$@"; do 33 | key="${i%% *}" 34 | raw_value="${i#* }" 35 | if ! echo "$raw_value" | jq -e . >/dev/null 2>&1; then 36 | value=$(printf '%s' "$raw_value" | jq -R .) 37 | else 38 | value="$raw_value" 39 | fi 40 | if [ "$first" = true ]; then 41 | first=false 42 | else 43 | echo -n "," 44 | fi 45 | printf '"%s":%s' "$key" "$value" 46 | done 47 | echo "}" 48 | } > "$output_path" 49 | } 50 | 51 | function write_filtered_config_list() { 52 | local file_path="$1" 53 | shift 54 | : > "$file_path" 55 | for file in "$@"; do 56 | echo "$file" >> "$file_path" 57 | done 58 | } 59 | 60 | function already_in_list() { 61 | local item="$1" 62 | shift 63 | for existing in "$@"; do 64 | [[ "$existing" == "$item" ]] && return 0 65 | done 66 | return 1 67 | } 68 | 69 | if [[ "$MERGE_BASE" == "$CIRCLE_SHA1" ]]; then 70 | if [ "$SAME_BASE_RUN" == "0" ]; then 71 | echo "Already in the base revision, exiting" 72 | echo "{}" > "$OUTPUT_PATH" 73 | : > "$filtered_config_list_file" 74 | exit 0 75 | fi 76 | if git rev-parse HEAD~1; then 77 | MERGE_BASE=$(git rev-parse HEAD~1) 78 | else 79 | # This is the empty tree SHA in case the repo has no commits and the previous command dosn't work 80 | MERGE_BASE="4b825dc642cb6eb9a060e54bf8d69288fbee4904" 81 | fi 82 | fi 83 | 84 | echo "Comparing $MERGE_BASE...$CIRCLE_SHA1" 85 | FILES_CHANGED=$(git -c core.quotepath=false diff --name-only "$MERGE_BASE" "$CIRCLE_SHA1") 86 | 87 | echo "$FILES_CHANGED" > $files_changed_file 88 | 89 | if [ -f "$MAPPING" ]; then 90 | # In this case MAPPING is a file with the mappings 91 | MAPPING=$(cat "$MAPPING") 92 | fi 93 | if [ -f "$EXCLUDE" ]; then 94 | # In this case EXCLUDE is a file with the exclusions 95 | EXCLUDE=$(cat "$EXCLUDE") 96 | fi 97 | 98 | filtered_mapping=() 99 | filtered_files_set=() 100 | while IFS= read -r line; do 101 | if is_mapping_line "$line"; then 102 | read -ra tokens <<< "$line" 103 | if [ "${#tokens[@]}" -eq 1 ]; then # 104 | MAPPING_PATH="${tokens[0]}" 105 | elif [ "${#tokens[@]}" -eq 2 ]; then # 106 | MAPPING_PATH="${tokens[0]}" 107 | CONFIG_FILE="${tokens[1]}" 108 | elif [ "${#tokens[@]}" -eq 3 ]; then # 109 | MAPPING_PATH="${tokens[0]}" 110 | PARAM_NAME="${tokens[1]}" 111 | PARAM_VALUE="${tokens[2]}" 112 | elif [ "${#tokens[@]}" -eq 4 ]; then # 113 | MAPPING_PATH="${tokens[0]}" 114 | PARAM_NAME="${tokens[1]}" 115 | PARAM_VALUE="${tokens[2]}" 116 | CONFIG_FILE="${tokens[3]}" 117 | else 118 | echo "Invalid mapping length of ${#tokens[@]}" 119 | exit 1 120 | fi 121 | regex="^$MAPPING_PATH\$" 122 | for i in $FILES_CHANGED; do 123 | PATH_EXCLUDED=0 124 | if [[ "$i" =~ $regex ]]; then 125 | while IFS= read -r ex; do 126 | regex_exclude="^$ex\$" 127 | if [[ "$i" =~ $regex_exclude ]]; then 128 | PATH_EXCLUDED=1 129 | break 130 | fi 131 | done <<< "$EXCLUDE" 132 | if [ "$PATH_EXCLUDED" -eq 1 ]; then 133 | continue 134 | fi 135 | 136 | if [ -n "$PARAM_VALUE" ]; then 137 | filtered_mapping+=("$PARAM_NAME $PARAM_VALUE") 138 | fi 139 | if [[ -n "$CONFIG_FILE" ]] && ! already_in_list "$CONFIG_FILE" "${filtered_files_set[@]}"; then 140 | filtered_files_set+=("$CONFIG_FILE") 141 | fi 142 | break 143 | fi 144 | done 145 | fi 146 | done <<< "$MAPPING" 147 | 148 | if [[ ${#filtered_mapping[@]} -eq 0 && -n "$PARAM_VALUE" ]]; then 149 | echo "No change detected in the paths defined in the mapping parameter" 150 | fi 151 | 152 | write_mappings "$OUTPUT_PATH" "${filtered_mapping[@]}" 153 | if [[ ${#filtered_files_set[@]} -eq 0 ]]; then 154 | filtered_files_set+=("$CONFIG_PATH") 155 | fi 156 | write_filtered_config_list "$filtered_config_list_file" "${filtered_files_set[@]}" 157 | -------------------------------------------------------------------------------- /src/scripts/generate-config.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | # GitHub's URL for the latest release, will redirect. 4 | GITHUB_BASE_URL="https://github.com/mikefarah/yq" 5 | DESTDIR="${DESTDIR:-/usr/local/bin}" 6 | VERSION="4.34.1" 7 | 8 | function installYq() { 9 | echo "Checking For yq + CURL" 10 | if command -v curl >/dev/null 2>&1 && ! command -v yq >/dev/null 2>&1; then 11 | echo "Installing yq v${VERSION}" 12 | 13 | uname -a | grep Darwin > /dev/null 2>&1 && OS='darwin' || OS='linux' 14 | PLATFORM=$(uname -m) 15 | RELEASE_URL="${GITHUB_BASE_URL}/releases/download/v${VERSION}/yq_${OS}_${PLATFORM}" 16 | 17 | # save the current checkout dir 18 | CHECKOUT_DIR=$(pwd) 19 | 20 | SCRATCH=$(mktemp -d || mktemp -d -t 'tmp') 21 | cd "$SCRATCH" || exit 22 | 23 | wget "${RELEASE_URL}" -O /usr/local/bin/yq &&\ 24 | chmod +x /usr/local/bin/yq 25 | 26 | command -v yq >/dev/null 2>&1 27 | 28 | echo "Installation finished" 29 | # Delete the working directory when the install was successful. 30 | cd "$CHECKOUT_DIR" || exit 31 | rm -r "$SCRATCH" 32 | return $? 33 | else 34 | command -v curl >/dev/null 2>&1 || { echo >&2 "PATH-FILTERING ORB ERROR: CURL is required. Please install."; exit 1; } 35 | command -v yq >/dev/null 2>&1 || { echo >&2 "PATH-FILTERING ORB ERROR: yq is required. Please install"; exit 1; } 36 | return $? 37 | fi 38 | } 39 | 40 | function generateConfig() { 41 | echo "Config list ===" 42 | 43 | cat "${PARAM_CONFIG_LIST_PATH}" 44 | 45 | echo 46 | echo "Generated YAML ===" 47 | 48 | touch "${PARAM_GENERATED_CONFIG_PATH}" 49 | 50 | # shellcheck disable=SC2154,SC2016 51 | < "${PARAM_CONFIG_LIST_PATH}" \ 52 | awk 'NF {$1=$1; printf "\"%s\" ", $0}' \ 53 | | xargs yq eval-all 'explode(.) | . as $item ireduce ({}; . * $item )' \ 54 | | tee "${PARAM_GENERATED_CONFIG_PATH}" 55 | } 56 | 57 | installYq 58 | generateConfig 59 | -------------------------------------------------------------------------------- /src/tests/README.md: -------------------------------------------------------------------------------- 1 | # tests/ 2 | 3 | This is where your testing scripts for whichever language is embedded in your orb live, which can be executed locally and within a CircleCI pipeline prior to publishing. 4 | 5 | # Testing Orbs 6 | 7 | This orb is built using the `circleci orb pack` command, which allows the _command_ logic to be separated out into separate _shell script_ `.sh` files. Because the logic now sits in a known and executable language, it is possible to perform true unit testing using existing frameworks such a [BATS-Core](https://github.com/bats-core/bats-core#installing-bats-from-source). 8 | 9 | ## **Example _command.yml_** 10 | 11 | ```yaml 12 | 13 | description: A sample command 14 | 15 | parameters: 16 | source: 17 | description: "source path parameter example" 18 | type: string 19 | default: src 20 | 21 | steps: 22 | - run: 23 | name: "Ensure destination path" 24 | environment: 25 | ORB_SOURCE_PATH: <> 26 | command: <> 27 | ``` 28 | 29 | ## **Example _command.sh_** 30 | 31 | ```bash 32 | 33 | CreatePackage() { 34 | cd "$ORB_SOURCE_PATH" && make 35 | # Build some application at the source location 36 | # In this example, let's assume given some 37 | # sample application and known inputs, 38 | # we expect a certain logfile would be generated. 39 | } 40 | 41 | # Will not run if sourced from another script. 42 | # This is done so this script may be tested. 43 | if [[ "$_" == "$0" ]]; then 44 | CreatePackage 45 | fi 46 | 47 | ``` 48 | 49 | We want our script to execute when running in our CI environment or locally, but we don't want to execute our script if we are testing it. In the case of testing, we only want to source the functions within our script,t his allows us to mock inputs and test individual functions. 50 | 51 | **A POSIX Compliant Source Checking Method:** 52 | 53 | ```shell 54 | # Will not run if sourced for bats. 55 | # View src/tests for more information. 56 | TEST_ENV="bats-core" 57 | if [ "${0#*$TEST_ENV}" == "$0" ]; then 58 | RUN CODE 59 | fi 60 | ``` 61 | 62 | **Example _command_tests.bats_** 63 | 64 | BATS-Core is a useful testing framework for shell scripts. Using the "source checking" methods above, we can source our shell scripts from within our BATS tests without executing any code. This allows us to call specific functions and test their output. 65 | 66 | ```bash 67 | # Runs prior to every test. 68 | setup() { 69 | # Load functions from our script file. 70 | # Ensure the script will not execute as 71 | # shown in the above script example. 72 | source ./src/scripts/command.sh 73 | } 74 | 75 | @test '1: Test Build Results' { 76 | # Mock environment variables or functions by exporting them (after the script has been sourced) 77 | export ORB_SOURCE_PATH="src/my-sample-app" 78 | CreatePackage 79 | # test the results 80 | grep -e 'RESULT="success"' log.txt 81 | } 82 | 83 | ``` 84 | 85 | Tests can contain any valid shell code. Any error codes returned during a test will result in a test failure. 86 | 87 | In this example, we grep the contents of `log.txt.` which should contain a `success` result if the `CreatePackage` function we had loaded executed successfully. 88 | 89 | ## See: 90 | - [BATS Orb](https://circleci.com/orbs/registry/orb/circleci/bats) 91 | - [Orb Testing CircleCI Docs](https://circleci.com/docs/2.0/testing-orbs) 92 | - [BATS-Core GitHub](https://github.com/bats-core/bats-core) 93 | --------------------------------------------------------------------------------