> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# roopakv/swissknife

This orb makes certain repeated operations (commonly used in monorepos) on Circle CI easier. Some of the functionality provided by this orb are, queuing up jobs within a workflow, queuing up workflows, finding artifacts from other jobs, fail a build if git dirty, run only if directory modified on branch, get the rerun job number, trigger pipeline if directory modified, publish github releases. #queue #runIfModified #artifacts #github #releases #triggerPipeline View this orb's source: https://github.com/roopakv/orbs


## Commands

### approve_job

This command approves a hold job(s) by name.
This requires a Circle CI token be set as $t


| Parameter | Type | Default | Description |
|---|---|---|---|
| `circleci-api-key` | env_var_name | CIRCLE_TOKEN | In case you use a different Environment Variable Name than CIRCLE_TOKEN, supply it here. |
| `job-name` | string |  | A list of comma separated hold jobs to approve |
| `kill-gracefully` | string | true | If true it completes and lets future steps continue |
| `run-on-branch` | string | * | The branches to actually wait on. By default this waits on all branches. If set to anything but
'*' the wait will run only on the specified branch
 |
| `when` | enum | on_success | Allows the user to set when conditions |

### beta-job-started-webhook

Send a webhook that a job has started. This is currently in beta and uses
the swissknife backend. To use this you need to have a swissknife API available
from beta.swissknife.dev. Set your Swissknife api key in the SWISSKNIFE_API_KEY env
variable.

This command sends a webhook on job start.

In order to have this webhook sent as early as possible, make this step as early as possible
on the job, preferably event before the checkout step.

All webhooks are signed with the Signing key set in Swissknife.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `destination` | string |  | The URL where the webhook should be posted to. |
| `fail-on-error` | boolean | true | Fails this step on error otherwise, this is best effort |
| `vcs-type` | string | gh | The type of VCS backing this repo. Defaults to gh for github |

### beta-workflow-started-webhook

Send a webhook that a workflow has started. This is currently in beta and uses
the swissknife backend. To use this you need to have a swissknife API available
from beta.swissknife.dev. Set your Swissknife api key in the SWISSKNIFE_API_KEY env
variable.

This command sends a webhook on workflow start. The swissknife backend de-dupes
workflow start across various jobs and it is ok to have this step run from many jobs,
only 1 webhook will be posted to the destination.

In order to have this webhook sent as early as possible, make this step as early as possible
on the job.

All webhooks are signed with the Signing key set in Swissknife.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `destination` | string |  | The URL where the webhook should be posted to. |
| `fail-on-error` | boolean | true | Fails this step on error otherwise, this is best effort |

### build_and_check_circle_config

This command builds the circle config in the specified directory. It validates the config.
If built with no validation errors you can choose to fail the build if what is
commited is different from what is built. This prevents divergence of code.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `circle-cli-version` | string | latest | Whether to install the latest version of the CLI. you can specify a specific version you
want to install as well. Remember not to include the "v". An example version would be
"0.1.8764". All releases can be found here: https://github.com/CircleCI-Public/circleci-cli/releases
 |
| `custom-config` | string | .circleci/config.yml | The file to check. By default this is .circleci/config.yml however in the case of monrepo mode,
this file can be overriden to check the coontinue config.
 |
| `custom-error-message` | string | Your circle source files and config.yml have diverged | The error message to fail with if git is directory. |
| `directory-of-src` | string | .circleci/src | The directory containing circleci config src relative to repo root. |
| `fail-if-dirty` | boolean | true | Fail if dirty
 |
| `install-circle-cli` | boolean | true | Will install the circle cli for you. If false you will need to install it. Needs sudo access.
 |
| `push-up-to-origin` | boolean | false | If there is a difference push up the built config to the current branch on origin.
This will work only if the required SSH keys for github or gitlab are added already.
For this to work, fail-if-dirty needs to be false.
 |
| `skip-push-on-branch` | string | master | The branches on which pushing is skipped
 |

### build_status_to_pagerduty

Send build status to PagerDuty integration.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch` | string | master | Runs only on specific branch. |
| `integration-key` | string |  | Integration key (a.k.a routing key) provided by PagerDuty. |
| `when` | string | on_fail | When to send the notification to PagerDuty. Possible values are on_fail and on_success |

### check-file-size

Fails a build if there is any file greater than a defined limit.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `base-branch` | string | master | The branch against which to check against. By default this check doesnt run against every
file in history where you might already have large files. We rather check current the current
head against the base branch. This check is meant specifically for PRs and is skipped on the base
branch.
 |
| `custom-error-message` | string | You checked in a file which is larger than one we allow. Remove this file and try again. | The error message to fail with. |
| `exclusion-pattern` | string | ^$ | Regex pattern containing files that can bypass this limit. By default nothing |
| `mac-or-linux-mode` | string | linux | Checking file size is done using stat which is different on mac vs linux. Defaults to linux mode |
| `size-limit` | integer |  | The max size of any file that can be added to the repo in bytes. |
| `use-divergence-point` | boolean | true | Find the divergence from the branch passed above, rather than the current HEAD |

### codeql-analysis

Runs CodeQL Analysis on your code base. This is a variant of the codeQL action and the results
can be optionally be reported to the Swissknife service for easy viewing. Currently python3,
golang and javascript are analyzed out of the box. Adding support for other languages is coming
soon.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `custom-init-steps` | steps |  | These steps are run after checkout giving you the chance to hook in and do some work
before codeQL analysis is done.
 |
| `languages` | string | auto | Set to comma separated list of languages to specify languages to analyze. If unset make
sure to set the GITHUB_TOKEN env variable to get the most prominent language in the repo
from github
 |
| `output-dir` | string | /home/circle/analysis | The directory where output is stored |
| `ram-limit` | string | 1024 | The amount of ram the analysis can use |
| `report-to-swissknife` | boolean | true | Whether or not to report to the swissknife service which makes analyzing results
easy. Setting this to true requires that the swissknife API key be set in the env var
SWISSKNIFE_API_KEY. You can find your key by signing in at beta.swissknife.dev
 |

### fail_if_dirty

Fail if git is dirty after running a set of steps.
For example running `go mod tidy` or `npm install` should not result in a dirty git directory.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `custom-error-message` | string | Files modified, failing | The error message to fail with if git is directory. |
| `invert-pattern` | boolean | false | Use the invert of the pattern above. Defaults to false. This orb uses grep to search so setting invert
uses the -v command.
 |
| `pattern` | string | .* | The regex to match for dirty files. By default if any file is dirty the command fails. If overriden
can be used to check for only say `package-lock.json` or `go.mod`.
 |
| `print-modified-files` | boolean | false | Whether to print the list of modified files. |
| `steps-to-run` | steps |  | The steps to run if the files mentioned are modified |

### filter-and-continue

This is the swissknife variation of path filtering described here.
https://github.com/CircleCI-Public/api-preview-docs/blob/path-filtering/docs/path-filtering.md#using-the-path-filtering-orb

This lets swissknife users continue without having to change their regexes and custom setup.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional-param-map` | string | {} | Any additional params that should be sent to the continue config. Pass in empty
json object `{}` if you have nothing specific to override.

Input should be json, something like '{"run_trigger_workflow": false}'
 |
| `base-branch` | string | master | The base branch for the repo. Based on the parameter "run-mode-for-base-branch",
you can either run all workflows or only the workflows of code modified in the last
commit.
 |
| `code-param-name-map` | string |  | Circle CI doesnt yet accept list inputs, so we accept a json blob as input. It is
a list of objects each of which contain "regex" to test for modified files and
"param_name" which causes that workflow to be triggered. the param_name is always
triggered with value true. In the future as Circle CI works with comparing values
in when clauses other param values will be accepted.

i.e. [{"regex": "/path/to/servercode", "param_name": "run_server_workflow"}]
 |
| `config-path` | string | .circleci/continue_config.yml | The location of the config to continue the pipeline with.
 |
| `pass-only-additional-params-thru` | boolean | false | If you are trying to run some jobs on your continue config but not look at what changed,
set this to true and pass the jobs you want ot run. This sets the additional params and ignores
everything from the code-param-name-map.
 |
| `pre-steps` | steps |  | Additional steps to run first in filter and continue |
| `run-mode-for-base-branch` | enum | run_all | The mechanism to use on the base branch. "run_all" simply runs all workflows on the base
branch (only the triggers passed into the map). "run_for_last_commit", looks at the code
modified in the last commit and Triggers a pipeline with all workflows according to that
commit. If your team uses only squash merges "run_for_last_commit" will work well.
Currently this command has not been tested for non squash merges to the base branch.
 |
| `search-mode` | enum | grep | By default searching for file matches uses grep with the extended matcher. The other option
involves using perl. Perl supports more complicated regexes such as negative lookahead etc.
Note that perl mode only works if perl is installed.
 |
| `use-divergence-point` | boolean | true | Find the divergence from the branch passed above, rather than the current HEAD. This is helpful
in branches. If true it looks at all code modified since the divergence from abse branch (say master),
otherwise if false it only looks at the last commit.
 |

### get-job-number

This command gets the job number given a name. If no workflow is specified, it uses the current
workflow, otherwise it uses the specifed workflow.
This can be used to retrieve artifacts from upstream jobs. The job number is saved to the bash
env with name SK_JOB_NUM
This requires a Circle CI token be set as $CIRCLE_TOKEN


| Parameter | Type | Default | Description |
|---|---|---|---|
| `job-name` | string |  | The name of the job to find the id of. |
| `workflow-id` | string | this | The workflow id to find the job in. Uses current worflow if no value passed in. |

### get_job_artifacts

This command gets artifacts from a Circle CI job and stores in a directory
This requires a Circle CI token be set as $CIRCLE_TOKEN


| Parameter | Type | Default | Description |
|---|---|---|---|
| `file-name` | string | NA | The name of the downloaded artifact. If not set, the remote name is used |
| `file-name-pattern` | string |  | the pattern of file name to download |
| `job-number` | env_var_name | CIRCLE_PREVIOUS_BUILD_NUM | the job number to pull artifacts from |
| `repo-name` | env_var_name | CIRCLE_PROJECT_REPONAME | The repo from which to get artifacts |
| `save-to-directory` | string | /tmp/swissknife/job_artifacts | Where to save the file to |
| `vcs-type` | string | github | What is the VCS for this project |

### get_rerun_job_number

This command gets the job number of which it is a rerun and sets it to the shell as RERUN_OF
This requires a Circle CI token be set as $CIRCLE_TOKEN


| Parameter | Type | Default | Description |
|---|---|---|---|
| `vcs-type` | string | github | What is the VCS for this project |

### modified-files

Finds all modified files for a given commit and base-branch.
This will only work on master branches if your team uses only squash merges.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `base-branch` | string | master | The base branch for the repo.
 |

### publish_github_release

This command publishes a release to the specified Github Repository using the tag name specified
The orb looks for $GITHUB_TOKEN otherwise you can pass it in as the github-token-variable parameter


| Parameter | Type | Default | Description |
|---|---|---|---|
| `github-token-variable` | env_var_name | GITHUB_TOKEN | Environment variable for Github Token |
| `repository` | env_var_name | CIRCLE_PROJECT_REPONAME | GitHub repository |
| `tag` | string |  | The tag that you want to tag your branch with. Required |
| `user` | env_var_name | CIRCLE_PROJECT_USERNAME | Username for the Github Project |

### run_if_modified

Run steps if files are modified

| Parameter | Type | Default | Description |
|---|---|---|---|
| `always-run-on-branch` | string |  | The branch to always run the steps on |
| `base-branch` | string | master | The branch against which to check against. This can also be a commit SHA |
| `check-last-commit-on-base-branch` | boolean | false | This will make the check run for the latest commit on the base branch.
 |
| `pattern` | string | .* | The regex to match files against. The command uses grep to search file names.
If you want to enforce starting with use ^. For checking if files in src/ or lib/ were modified,
the pattern to use would be ^src.*|^lib.*
 |
| `steps-to-run` | steps |  | The steps to run if the files mentioned are modified |
| `use-divergence-point` | boolean | false | Find the divergence from the branch passed above, rather than the current HEAD |

### run_on_branch

Run steps if on branch

| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch-pattern` | string | master | The pattern of branches to look for |
| `steps-to-run` | steps |  | The steps to run if the files mentioned are modified |

### sftp-upload

This command uploads files in a directory to an FTP server.

This command auto confirms SFTP host and does not delete files that have been
deleted locally. i.e. one way sync.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `directory-to-upload` | string |  | the directory to upload |
| `host` | string |  | The host to where we are uploading. Use format host:port |
| `password` | env_var_name | SK_FTP_PASSWORD | The password to auth with. |
| `save-to-directory` | string |  | Where to save the files to on the remote server. |
| `username` | env_var_name | SK_FTP_USERNAME | The username to auth with. |

### sk-checkout

Checks out code with the SWISSKNIFE_SHA. This is mainly to be used with trigger-workflows-for-all-modified.
Note that this job by default overwrites the CIRCLE_SHA1 as well as adds SWISSKNIFE_SHA1. You can choose to not
to overwrite the SHA using the overwrite-sha param


| Parameter | Type | Default | Description |
|---|---|---|---|
| `overwrite-sha` | boolean | true | Whether or not to overwrite CIRCLE_SHA1. This is sort of a best effort basis, since
Circle uses some magic to inject the circle variables.
 |
| `swissknife_sha` | string |  | The swissknife sha. This should always be the pipeline param "swissknife_sha". Since Circle prevents
orbs from reading pipeline params this needs to be explicitly passed in with the value
"<< pipeline.parameters.swissknife_sha >>"
 |

### trigger-pipeline

Triggers a pipeline on given branch. Also allows to install the trigger script and not trigger into
/tmp/swissknife/trigger_pipeline.sh
it can be called with the arguments as follows
/tmp/swissknife/trigger_pipeline.sh vcstype username reponame branch '{"custom_params": "here"}'
OR
/tmp/swissknife/trigger_pipeline.sh vcstype username reponame -t tag '{"custom_params": "here"}'


| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch` | env_var_name | CIRCLE_BRANCH | The branch to trigger the pipeline on |
| `custom-parameters` | string | {} | Custom parameters passed to the pipeline |
| `install-skip-trigger` | boolean | false | Adds the script to /tmp/swissknife/trigger_pipeline.sh and don't trigger flow |
| `repo-name` | env_var_name | CIRCLE_PROJECT_REPONAME | The repo to trigger the workflow on |
| `tag` | env_var_name | CIRCLE_TAG | The tag to trigger the pipeline on |
| `user` | env_var_name | CIRCLE_PROJECT_USERNAME | Username for the Github Project |
| `vcs-type` | string | github | What is the VCS for this project |

### trigger-workflows-for-all-modified

Triggers multiple workflows in one pipeline. The decision on which
workflows are based on the files that have been modified. This command
is specifically useful in monorepos. If there are multiple projects within
a monorepo this command lets you trigger one pipeline with all the workflows
corresponding to the files that have been modified.

This job (similar to other jobs on siwssknife) expects
CIRCLE_TOKEN is set as an env variable.

On the base branch (generally master), you can choose to run all workflows
or just the workflows which have code modified.

Since CircleCI inputs don't allow for lists, the input to this job
is JSON. It is a list of objects each of which contain "regex" to test for modified
files and "parameter_name" which causes that workflow to be triggered.

Generally any job with this command should have no other steps, however we leave it
as a command to allow flexibility and not force custom executors etc.

This command is fairly complex, and the best way to understand the use of this
command, take a look at the example at https://github.com/swissknife/circle-monorepo


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional-param-map` | string |  | Any additional params that should be sent with the workflow trigger. Generally
there needs to be one additional param to make sure the workflow that contains
this command is not triggered resulting in an infinite loop.

Rather than just allow one additional param we accept a json so other params can
be passed in. This param is required in order to make sure no infinite loops occur.

Input should be json, something like '{"run_trigger_workflow": false}'
 |
| `base-branch` | string | master | The base branch for the repo. Based on the parameter "run-mode-for-base-branch",
you can either run all workflows or only the workflows of code modified in the last
commit.
 |
| `code-param-name-map` | string |  | Circle CI doesnt yet accept list inputs, so we accept a json blob as input. It is
a list of objects each of which contain "regex" to test for modified files and
"param_name" which causes that workflow to be triggered. the param_name is always
triggered with value true. In the future as Circle CI works with comparing values
in when clauses other param values will be accepted.

i.e. [{"regex": "/path/to/servercode", "param_name": "run_server_workflow"}]
 |
| `repo-name` | env_var_name | CIRCLE_PROJECT_REPONAME | The repo to trigger the workflow on |
| `run-mode-for-base-branch` | enum | run_all | The mechanism to use on the base branch. "run_all" simply runs all workflows on the base
branch (only the triggers passed into the map). "run_for_last_commit", looks at the code
modified in the last commit and Triggers a pipeline with all workflows according to that
commit. If your team uses only squash merges "run_for_last_commit" will work well.
Currently this command has not been tested for non squash merges to the base branch.
 |
| `search-mode` | enum | grep | By default searching for file matches uses grep with the extended matcher. The other option
involves using perl. Perl supports more complicated regexes such as negative lookahead etc.
Note that perl mode only works if perl is installed.
 |
| `use-divergence-point` | boolean | true | Find the divergence from the branch passed above, rather than the current HEAD. This is helpful
in branches. If true it looks at all code modified since the divergence from abse branch (say master),
otherwise if false it only looks at the last commit.
 |
| `use-swissknife-sha` | boolean | false | Adds the current commit sha to the trigger so that you can checkout the relevant commit. This is mainly
because Circle does not let you specify commit when triggering a pipeline. If you suspect your repo has
a high velocity and would like ot make sure that you are definitely triggering on the same commit set this
to true.

Note that this has additional requirements:
- You need to use the sk-checkout command which is a wrapper on the checkout command
- You need to add a pipeline param 'swissknife_sha' to your config and pass it in to the swissknife/sk-checkout command

You can see an example of this in the example repo above.
 |
| `user` | env_var_name | CIRCLE_PROJECT_USERNAME | Username for the Github Project |
| `vcs-type` | string | github | What is the VCS for this project |

### trigger_pipeline_if_modified

Triggers a workflow if directory / file is modified. Continues if not

| Parameter | Type | Default | Description |
|---|---|---|---|
| `always-trigger-on-branch` | string |  | The branch to always run the steps on |
| `base-branch` | string | master | The branch against which to check against. This can also be a commit SHA |
| `custom-parameters` | string | {} | Custom parameters passed to the pipeline |
| `pattern` | string | .* | The regex to match files against. The command uses grep to search file names.
If you want to enforce starting with use ^. For checking if files in src/ or lib/ were modified,
the pattern to use would be ^src.*|^lib.*
 |
| `repo-name` | env_var_name | CIRCLE_PROJECT_REPONAME | The repo to trigger the workflow on |
| `use-divergence-point` | boolean | false | Find the divergence from the branch passed above, rather than the current HEAD |
| `user` | env_var_name | CIRCLE_PROJECT_USERNAME | Username for the Github Project |
| `vcs-type` | string | github | What is the VCS for this project |

### ttl-cache

Creates a cache which has a custom expiry. This kind of cache helps things like linting where the
cache could be busted say once a day making lint jobs much faster. Other examples of use cases
are go build cache, webpack etc.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `base-branch` | string | master | The base branch for the repo. This is usually master or main.
 |
| `cache-key-prefix` | string |  | The cache key prefix to differentiate between caches.
 |
| `include-branch-in-cache` | boolean | true | If set this will include the branch will be included in the cache. This means that caches
will not be shared across branches. To create a cache that is only restored from the base
branch set trust-base-branch-cache-only.
 |
| `save-cache-directory-1` | string | /tmp/swissknife/cache/dir1 | Path 1 to save in cache |
| `save-cache-directory-2` | string | /tmp/swissknife/cache/dir2 | Path 2 to save in cache |
| `save-cache-directory-3` | string | /tmp/swissknife/cache/dir3 | Path 3 to save in cache |
| `trust-base-branch-cache-only` | boolean | true | If set this will restore cache only from master and when saving on non master branches will
use a common key. This is useful when using the cache for things like linting when only a
cache created in master is trusted.
 |
| `ttl-period` | enum | 1-day | The time period for busting the cache. Note that depending on how long the job takes, should
be a factor into how often to bust. We don't want to do it too often or too few times.
 |
| `type` | enum |  | Whether this is save or restore step. |

### wait_for_job

This command waits for a job(s) in this workflow. Since right now Circle CI doesn't let
you queue up jobs irrespective of whether they fail or not. This is a faux queue where
the command stalls till the other job succeeds.
This requires a Circle CI token be set as $CIRCLE_TOKEN


| Parameter | Type | Default | Description |
|---|---|---|---|
| `circleci-api-key` | env_var_name | CIRCLE_TOKEN | In case you use a different Environment Variable Name than CIRCLE_TOKEN, supply it here. |
| `job-name` | string |  | The job or jobs on which to wait. If job not found continue immediately. For multiple jobs the list must be comma separated. |
| `kill-gracefully` | string | true | If true and time exceeds max wait time, completes and lets future steps continue |
| `max-wait-time` | string | 1800 | The max wait time in seconds a job should wait for before killing itself.
 |
| `run-on-branch` | string | * | The branches to actually wait on. By default this waits on all branches. If set to anything but
'*' the wait will run only on the specified branch
 |
| `sleep-time-between-checks` | string | 30 | How long to sleep between checks. |

### wait_for_workflow

This command waits for running workflows of a kind on a given branch to complete. Adding This
as the first step in a job will make the job wait till it is the only running workflow.
This requires a Circle CI token be set as $CIRCLE_TOKEN


| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch-to-consider` | string | master | The branch on which we will wait for workflows. If set to "all" this will wait across all branches |
| `kill-gracefully` | string | true | If true and time exceeds max wait time, dies without failing the job |
| `max-wait-time` | string | 600 | The max wait time in seconds a job should wait for before killing itself.
 |
| `repo-name` | env_var_name | CIRCLE_PROJECT_REPONAME | The environment variable that holds the workflows repo. Defaults to the calling repo. |
| `run-on-branch` | string | * | The branches to actually wait on. By default this waits on all branches. If set to anything but
'*' the wait will run only on the specified branch
 |
| `sleep-time-between-checks` | string | 30 | How long to sleep between checks. |
| `vcs-type` | string | github | What is the VCS for this project |
| `workflow-name` | string | * | The type of workflows to wait for. This can be a regex |

## Jobs

### codeql-analysis

Runs CodeQL Analysis on your code base. This is a variant of the codeQL action and the results
can be optionally be reported to the Swissknife service for easy viewing. Currently python3,
golang and javascript are analyzed out of the box. Adding support for other languages is coming
soon. Right now results are saved as artifacts and support for viewing results on
beta.swissknife.dev is also coming soon.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `custom-init-steps` | steps |  | These steps are run after checkout giving you the chance to hook in and do some work
before codeQL analysis is done.
 |
| `languages` | string | auto | Set to comma separated list of languages to specify languages to analyze. If unset make
sure to set the GITHUB_TOKEN env variable to get the most prominent language in the repo
from github
 |
| `output-dir` | string | /home/circleci/analysis | The directory where output is stored |
| `ram-limit` | string | 1024 | The amount of ram the analysis can use |
| `report-to-swissknife` | boolean | true | Whether or not to report to the swissknife service which makes analyzing results
easy. Setting this to true requires that the swissknife API key be set in the env var
SWISSKNIFE_API_KEY. You can find your key by signing in at beta.swissknife.dev
 |
| `resource-class` | string | medium | The resource class for the executor |

### filter-and-continue

Continues a pipeline in the `setup` state based with static config and a set of pipeline parameters based on the changes in this push.
This is the Swissknife variation of path filtering described here. https://github.com/CircleCI-Public/api-preview-docs/blob/path-filtering/docs/path-filtering.md#using-the-path-filtering-orb
This lets swissknife users continue without having to change their regexes and custom setup.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `additional-param-map` | string | {} | Any additional params that should be sent to the continue config. Pass in empty
json object `{}` if you have nothing specific to override.

Input should be json, something like '{"run_trigger_workflow": false}'
 |
| `base-branch` | string | master | The base branch for the repo. Based on the parameter "run-mode-for-base-branch",
you can either run all workflows or only the workflows of code modified in the last
commit.
 |
| `code-param-name-map` | string |  | Circle CI doesnt yet accept list inputs, so we accept a json blob as input. It is
a list of objects each of which contain "regex" to test for modified files and
"param_name" which causes that workflow to be triggered. the param_name is always
triggered with value true. In the future as Circle CI works with comparing values
in when clauses other param values will be accepted.

i.e. [{"regex": "/path/to/servercode", "param_name": "run_server_workflow"}]
 |
| `config-path` | string | .circleci/continue_config.yml | The location of the config to continue the pipeline with.
 |
| `pass-only-additional-params-thru` | boolean | false | If you are trying to run some jobs on your continue config but not look at what changed,
set this to true and pass the jobs you want ot run. This sets the additional params and ignores
everything from the code-param-name-map.
 |
| `run-mode-for-base-branch` | enum | run_all | The mechanism to use on the base branch. "run_all" simply runs all workflows on the base
branch (only the triggers passed into the map). "run_for_last_commit", looks at the code
modified in the last commit and Triggers a pipeline with all workflows according to that
commit. If your team uses only squash merges "run_for_last_commit" will work well.
Currently this command has not been tested for non squash merges to the base branch.
 |
| `search-mode` | enum | grep | By default searching for file matches uses grep with the extended matcher. The other option
involves using perl. Perl supports more complicated regexes such as negative lookahead etc.
Note that perl mode only works if perl is installed.
 |
| `use-divergence-point` | boolean | true | Find the divergence from the branch passed above, rather than the current HEAD. This is helpful
in branches. If true it looks at all code modified since the divergence from abse branch (say master),
otherwise if false it only looks at the last commit.
 |

### queue_up_workflow

This job waits for workflows based on the parameters passed in. It requires a
Circle CI token be set as $CIRCLE_TOKEN. Make other jobs in your workflow require this
one to start which will result in queueing up workflows.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch-to-consider` | string | master | The branch on which we will wait for workflows |
| `kill-gracefully` | string | true | If true and time exceeds max wait time, dies without failing the job |
| `max-wait-time` | string | 600 | The max wait time in seconds a job should wait for before killing itself.
 |
| `sleep-time-between-checks` | string | 30 | How long to sleep between checks. |
| `vcs-type` | string | github | What is the VCS for this project |
| `workflow-name` | string | * | The type of workflows to wait for. This can be a regex |

## Executors

### codeql-runner

### packer1-5-4

## Examples

### queue_jobs_within_workflow

This command waits for another job in this workflow. Since right now Circle doesnt let
you queue up jobs irrespective of whether they fail or not. This is a faux queue where
the command stalls till the other job succeeds.


```yaml
version: '2.1'
orbs:
  swissknife: roopakv/swissknife@x.y
jobs:
  second-job:
    docker:
      - image: circleci/node:latest
    steps:
      - swissknife/wait_for_job:
          job-name: First job name
      - run:
          command: >
            echo "This code will run only after first job is finished (either
            successfully or failure)"
          name: Run after first job
    working_directory: /home/circleci/project
workflows: null
```

### queue_workflows

This command waits for running workflows of a kind on a given branch to complete. Adding This
as the first step in a job will make the job wait till it is the only running workflow.
This requires a Circle CI token be set as $CIRCLE_TOKEN


```yaml
version: '2.1'
orbs:
  swissknife: roopakv/swissknife@x.y
jobs:
  some-job:
    docker:
      - image: circleci/node:latest
    steps:
      - swissknife/wait_for_workflow:
          max-wait-time: '1800'
          workflow-name: ^(staging|production|sandbox|regression-staging|regression-sandbox)$
    working_directory: /home/circleci/project
workflows: null
```

### run_workflow_only_if_files_modified

Triggers a workflow if directory / file is modified. Continues if not. In this
example, we have two pipeline vars run_main_workflow and trigger_other_workflow, the
main workflow  has a job called some-job which runs another workflow for
integration tests. It is set up this way since we dont want to run integration tests for every change


```yaml
version: '2.1'
orbs:
  swissknife: roopakv/swissknife@x.y
jobs:
  trigger-needed-workflows:
    docker:
      - image: circleci/node:latest
    steps:
      - checkout
      - swissknife/trigger_pipeline_if_modified:
          always-trigger-on-branch: master
          custom-parameters: '{"run_main_workflow": false, "run_custom_integration_tests": true}'
          pattern: ^(directory|\.circleci).*
          use-divergence-point: true
          workflow-name: monitors-ci
workflows: null
```