{"id":15140304,"url":"https://github.com/emmeowzing/dynamic-continuation-orb","last_synced_at":"2025-10-23T15:31:56.674Z","repository":{"id":37603065,"uuid":"452800936","full_name":"emmeowzing/dynamic-continuation-orb","owner":"emmeowzing","description":"CircleCI orb for directory-targeted dynamically continued pipelines","archived":false,"fork":false,"pushed_at":"2025-01-21T17:40:26.000Z","size":257,"stargazers_count":22,"open_issues_count":22,"forks_count":12,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-30T19:22:31.014Z","etag":null,"topics":["github","probot"],"latest_commit_sha":null,"homepage":"https://circleci.com/developer/orbs/orb/bjd2385/dynamic-continuation","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emmeowzing.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"ko_fi":"emmeowzing"}},"created_at":"2022-01-27T18:37:21.000Z","updated_at":"2024-11-18T14:40:07.000Z","dependencies_parsed_at":"2023-08-11T09:38:09.156Z","dependency_job_id":"c1783aab-9334-4413-ab5e-659884c78644","html_url":"https://github.com/emmeowzing/dynamic-continuation-orb","commit_stats":{"total_commits":186,"total_committers":11,"mean_commits":16.90909090909091,"dds":0.7150537634408602,"last_synced_commit":"8cf004b77abcc226b3fa45e7dfd1f08fa18f12d4"},"previous_names":["emmeowzing/dynamic-continuation-orb","bjd2385/dynamic-continuation-orb"],"tags_count":49,"template":false,"template_full_name":"emmeowzing/circleci-orb-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmeowzing%2Fdynamic-continuation-orb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmeowzing%2Fdynamic-continuation-orb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmeowzing%2Fdynamic-continuation-orb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmeowzing%2Fdynamic-continuation-orb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emmeowzing","download_url":"https://codeload.github.com/emmeowzing/dynamic-continuation-orb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237852534,"owners_count":19376704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github","probot"],"created_at":"2024-09-26T08:02:01.440Z","updated_at":"2025-10-23T15:31:51.344Z","avatar_url":"https://github.com/emmeowzing.png","language":"Shell","funding_links":["https://ko-fi.com/emmeowzing"],"categories":[],"sub_categories":[],"readme":"# CircleCI dynamic continuation orb\n\n[![CircleCI](https://dl.circleci.com/status-badge/img/gh/emmeowzing/dynamic-continuation-orb/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/emmeowzing/dynamic-continuation-orb/tree/main)\n\nThis orb is a merger of CircleCI's [path-filtering](https://circleci.com/developer/orbs/orb/circleci/path-filtering) and [continuation](https://circleci.com/developer/orbs/orb/circleci/continuation) orbs. It enables engineers to create configs under `.circleci/` that only run when there are code changes in coinciding directory paths. Directory-targeted dynamically-executed pipelines offer engineers reduced execution time, and by extension, reduced CI costs.\n\n\u003cp align=\"center\" width=\"100%\"\u003e\n  \u003cimg width=\"75%\" src=\"img/example.png\" alt=\"example\"\u003e\n\u003c/p\u003e\n\nThis orb is based on a [published example](https://github.com/circle-makotom/circle-advanced-setup-workflow) of advanced configuration with continuations from CircleCI.\n\nSee my [article on Medium](https://medium.com/@ejd2385/dynamic-continuations-in-circleci-d7516ae5c6f2) about dynamic continuations for a simple introduction to using this orb.\n\nFor users familiar with GitHub actions, this orb is analogous to the [paths-filter](https://github.com/dorny/paths-filter) action.\n\n## Usage\n\nGet up-and-running with dynamically continued pipelines in these 4 steps:\n\n1. Add this orb, a `continue` job to your CI config (`.circleci/config.yml`), and the `setup` keyword, such as\n\n   ```shell\n   setup: true\n\n   orbs:\n     dynamic: bjd2385/dynamic-continuation@\u003cversion\u003e\n\n   workflows:\n     on-commit:\n       jobs:\n         - dynamic/continue:\n             base-revision: main\n             context: circleci\n   ```\n\n   \u003e ***Note:** pipeline config files under `.circleci/` are automatically detected by default (cf. [`auto-detect`](https://circleci.com/developer/orbs/orb/bjd2385/dynamic-continuation#jobs-continue) in the documentation).*\n\n2. Enable **setup workflows** in your project under **Advanced Settings**.\n\n   \u003cp align=\"center\" width=\"100%\"\u003e\n     \u003cimg width=\"100%\" src=\"img/dynamic-config.png\" alt=\"dynamic config\"\u003e\n   \u003c/p\u003e\n\n3. The `circleci` context in your organization must have two environment variables set for the orb to reference, including\n    - `CIRCLE_ORGANIZATION` (in my case, this is set to `bjd2385`), and\n    - `CIRCLE_TOKEN`, which contains your CircleCI API token.\n\n4. Move workflows to their new configs in `.circleci/\u003cconfig-name\u003e.yml`. Configs should be complete and pass a `circleci config validate`-check.\n\n## How it works\n\nThe orb will automatically detect and run a workflow (we'll call it `\u003cmodule\u003e`) if any of the following conditions are met.\n\n1. If `.circleci/\u003cmodule\u003e.yml` changes (this is configurable, enabled by default).\n2. If changes have been detected within the `\u003cmodule\u003e/`'s directory on your branch against the repository's default branch (defaults to `main`). See [below](#filtering-or-ignoring-changed-files) on how to filter out CI runs from specific changed files.\n3. If, following merge to the default branch, there are changes to `.circleci/\u003cmodule\u003e.yml` or under `\u003cmodule\u003e/`, when diffing against the former commit (you must perform a merge commit for this to work properly).\n\nThese conditions can be overridden, and all workflows forced to run, if the `force-all` parameter is set to `true` on the `continue` job.\n\n### Examples\n\n#### Basic directory layout\n\n\u003cdetails\u003e\n  \u003csummary\u003eShow\u003c/summary\u003e\n\nIf you have a directory layout\n\n```shell\n.circleci/config.yml\nterraform/\nscripts/\nsrc/\n```\n\nwith the addition of this orb, a user could define targeted configs\n\n```shell\n.circleci/config.yml\n.circleci/terraform.yml  # targets changes under the 'terraform/' directory\n.circleci/scripts.yml    # targets changes under the 'scripts/' directory\n.circleci/src.yml        # targets changes under the 'src/' directory\nterraform/\nscripts/\nsrc/\n```\n\nThe `dynamic/continue` workflow would look like\n\n```yaml\nsetup: true\n\norbs:\n  dynamic: bjd2385/dynamic-continuation@\u003cversion\u003e\n\nworkflows:\n  on-commit:\n    jobs:\n      - dynamic/continue:\n          context: circleci\n          modules: |\n            /terraform\n            /scripts\n            /src\n```\n\nOnce again, the workflows will only execute if any code changes are introduced to the containing \"module\".\n\nFor example: if no changes are made on your branch within the `terraform/` directory, the `.circleci/terraform.yml` CI config will not be executed.\n\n\u003c/details\u003e\n\n#### Nested directories\n\n\u003cdetails\u003e\n  \u003csummary\u003eShow\u003c/summary\u003e\n\nLet's build off of the directory layout above, but add some environments.\n\n```shell\n.circleci/config.yml\nterraform/\n  development/\n  production/\n  staging/\nscripts/\nsrc/\n  pkg1/\n  pkg2/\n```\n\nWe may write further targeted configs\n\n```shell\n.circleci/config.yml\n.circleci/terraform.development.yml   # target specific changes under 'terraform/development/'\n.circleci/terraform.production.yml    # target specific changes under 'terraform/production/'\n.circleci/terraform.staging.yml       # target specific changes under 'terraform/staging/'\n.circleci/scripts.yml\n.circleci/src.pkg1.yml                # target specific changes under 'src/pkg1/'\n.circleci/src.pkg2.yml                # target specific changes under 'src/pkg2/'\n```\n\nwith a corresponding `dynamic/continue` workflow in our standard `config.yml`\n\n```yaml\nsetup: true\n\norbs:\n  dynamic: bjd2385/dynamic-continuation@\u003cversion\u003e\n\nworkflows:\n  on-commit:\n    jobs:\n      - dynamic/continue:\n          context: circleci\n          modules: |\n            /terraform/development\n            /terraform/production\n            /terraform/staging\n            /scripts\n            /src/pkg1\n            /src/pkg2\n```\n\nNote that the filenames denote additional directory structure with dots `.`, whereas our modules may contain dots `.` or slashes `/`. Thus, the following list of modules is also valid, albeit potentially harder to follow.\n\n```yaml\nmodules: |\n  terraform.development\n  terraform.production\n  terraform.staging\n  scripts\n  src.pkg1\n  src.pkg2\n```\n\n\u003c/details\u003e\n\n#### Filtering, ignoring and including file changes\n\n\u003cdetails\u003e\n  \u003csummary\u003eShow\u003c/summary\u003e\n\nAt times, there may be files that change in modules that should _not_ cause workflows to run. These could include, as an example, updated markdown or README-like files.\n\nTo solve this problem, the orb has the ability to read an optional `.gitignore`-like filter on each module, named `.circleci/\u003cmodule\u003e.ignore`, to prevent detected changed files on your PR from enabling workflows.\n\n\u003c/details\u003e\n\n##### Ignore file changes\n\n\u003cdetails\u003e\n  \u003csummary\u003eShow\u003c/summary\u003e\n\nStarting with the same directory layout as above, we could add `.gitignore`-like files\n\n```shell\n.circleci/config.yml\n.circleci/terraform.yml\n.cirlceci/terraform.ignore  # optionally ignore changes under 'terraform/' directory\n.circleci/scripts.yml\n.cirlceci/scripts.ignore    # optionally ignore changes under 'scripts/' directory\n.circleci/src.yml\n.cirlceci/src.ignore        # optionally ignore changes under 'src/' directory\nterraform/\nscripts/\nsrc/\n```\n\nThese files are automatically referenced, and do not need to be explicitly specified, with a job as\n\n```yaml\nworkflows:\n  on-commit:\n    jobs:\n      - dynamic/continue:\n          context: circleci\n          # auto-detect: true\n```\n\nor, exactly the same as above.\n\n\u003c/details\u003e\n\n##### Include additional file changes\n\n\u003cdetails\u003e\n  \u003csummary\u003eShow\u003c/summary\u003e\n\nWe can create additional pipeline file change dependencies throughout the repo within the same `*.ignore`-files. For example, suppose we have a subdirectory `scripts/terraform/`, and we want changes to files under this subdirectory to enable the pipeline defined in `.circleci/terraform.yml`; we can add\n\n```text\n!scripts/terraform/*\n```\n\nto `.circleci/terraform.ignore`, as described in the [Git documentation](https://git-scm.com/docs/gitignore#_pattern_format).\n\n\u003c/details\u003e\n\n#### Specify an alternate workflow for your repository's root directory\n\n\u003cdetails\u003e\n  \u003csummary\u003eShow\u003c/summary\u003e\n\nIt is possible to run a workflow targeting the root of a repository's directory structure, offering overlapping workflows and more flexibility on file changes when paired with the above strategies. We can accomplish this by specifying `.` or `/` as a module. For example,\n\n```yaml\nworkflows:\n  on-commit:\n    jobs:\n      - dynamic/continue:\n          context: circleci\n          auto-detect: true\n          root-config: app  # Defaults to 'app.yml' and 'app.ignore' under .circleci/, should the orb detect a '.'- or '/'-root module\n```\n\nNote that this requires you define an `app.yml` (though this root config's name is configurable), at  minimum, under `.circleci/`, for the orb to process.\n\n\u003c/details\u003e\n\n## Config validation with `pre-commit`\n\nStandard CircleCI config validation pre-commit hooks will only validate the default config at `.circleci/config.yml`. Please use this project's pre-commit hook to validate any additional configs you've created.\n\nAppend the following to your `.pre-commit-config.yaml` -\n\n```yaml\n- repo: https://github.com/bjd2385/dynamic-continuation-orb\n    rev: v\u003cversion\u003e\n    hooks:\n      - id: circleci-config-validate\n```\n\nYou must have the [`circleci`](https://circleci.com/docs/2.0/local-cli/) CLI installed.\n\n## Development\n\nThis orb has been developed in _unpacked_ form. You may view its packed source with\n\n```shell\nyarn orb:pack  # creates a file 'orb.yml'\n```\n\nValidate an orb definition with\n\n```shell\nyarn orb:validate\n```\n\nWhen you're done with development, you may clean up the packed source with\n\n```shell\nyarn orb:clean\n```\n\n### `pre-commit`\n\nThis repository uses `pre-commit` to uphold certain code styling and standards. You may install the hooks listed in [`.pre-commit-config.yaml`](.pre-commit-config.yaml) with\n\n```shell\nyarn install:pre-commit-hooks\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femmeowzing%2Fdynamic-continuation-orb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femmeowzing%2Fdynamic-continuation-orb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femmeowzing%2Fdynamic-continuation-orb/lists"}