> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt) # circleci/orb-tools An orb for creating orbs. This orb is automatically implemented as a part of the generated config produced by the Orb Development Kit. To get started writing your own orb, see the docs linked in the "Homepage" url below. ## Jobs ### continue Continue the pipeline for testing. This job will inject your orb source code into the provided config file prior to continuing the pipeline. With the orb injected, it will be possible to test your orbs features as if it were published. | Parameter | Type | Default | Description | |---|---|---|---| | `attach_workspace` | boolean | true | By default, the workspace will be attached to the job at the orb_dir path. If you are implementing a custom workflow, you may want to disable this behavior. | | `checkout` | boolean | true | If you do not wish to checkout the source code, you may disable this behavior. Replace the checkout and add your own command or steps via the 'pre-steps' parameter in your workflow. | | `circleci_api_host` | string | https://circleci.com | Host URL of CircleCI API. If you are using CircleCI server, this value should be set. | | `circleci_app_host` | string | https://app.circleci.com | Host URL of CircleCI Web UI. If you are using CircleCI server, this value should be set. | | `circleci_ip_ranges` | boolean | false | Enables jobs to go through a set of well-defined IP address ranges. | | `config_path` | string | .circleci/test-deploy.yml | Path to the next config file to execute. By default, this will execute the "test_deploy" workflow. | | `executor` | executor | default | The executor to use for this job. By default, this will use the "default" executor provided by this orb. | | `inject_orb` | boolean | true | If true, the orb will be injected into the provided config file. | | `orb_dir` | string | dist | Directory containing packed orb source. Path must be absolute or relative to the working directory. Should match the "orb_dir" of the "pack" job. | | `orb_file_name` | string | orb.yml | The orb output file name. The orb will be named this value in the output directory. Path must be absolute or relative to the working directory. | | `orb_name` | string | | The reference name of the orb to be injected in the config, no namespace or version number. e.g. "orb-tools" | | `pipeline_number` | integer | | The CircleCI pipeline number. Required to be passed in as a parameter for compatibility. | | `vcs_type` | enum | | The VCS type. Required to be passed in as a parameter for compatibility. Should be configured automatically by the Orb Development Kit. | ### lint Lint all YAML files in the project. A ".yamllint" file will be generated for you automatically by the Orb Development Kit. | Parameter | Type | Default | Description | |---|---|---|---| | `checkout` | boolean | true | If you do not wish to checkout the source code, you may disable this behavior. Replace the checkout and add your own command or steps via the 'pre-steps' parameter in your workflow. | | `circleci_ip_ranges` | boolean | false | Enables jobs to go through a set of well-defined IP address ranges. | | `executor` | executor | python | The executor to use for this job. By default, this will use the "python" executor provided by this orb. | | `pip_break` | boolean | false | Put --break-system-packages flag on pip install | | `source_dir` | string | src | Path to the orb source. Path must be absolute or relative to the working directory. | ### pack Packs the orb source into a single YAML file and validates for orb config errors. For CircleCI server servers, please ensure you set the `circleci-api-host` job parameter and CIRCLE_TOKEN environment variable. | Parameter | Type | Default | Description | |---|---|---|---| | `checkout` | boolean | true | If you do not wish to checkout the source code, you may disable this behavior. Replace the checkout and add your own command or steps via the 'pre-steps' parameter in your workflow. | | `circleci_api_host` | string | https://circleci.com | Host URL of CircleCI API. If you are using self_hosted CircleCI, this value should be set. | | `circleci_ip_ranges` | boolean | false | Enables jobs to go through a set of well-defined IP address ranges. | | `executor` | executor | default | The executor to use for this job. By default, this will use the "default" executor provided by this orb. | | `orb_dir` | string | dist | The orb output directory. The orb will be named "orb.yml" by default in this directory and persisted to the workspace. Path must be absolute or relative to the working directory. | | `orb_file_name` | string | orb.yml | The orb output file name. The orb will be named this value in the output directory. Path must be absolute or relative to the working directory. | | `org_id` | string | | The organization ID. Only necessary if your orb depends on private orbs in the same namespace. You can use "orb_slug" instead if you prefer. | | `org_slug` | string | | The organization slug (e.g., gh/MyOrg). Only necessary if your orb depends on private orbs in the same namespace. You can use "org_id" instead if you prefer. | | `persist_to_workspace` | boolean | true | By default, the orb_dir will be persisted to a workspace so that it may be used by the "continue" job. If you are implementing a custom workflow, you may want to disable this behavior. | | `source_dir` | string | src | Path to the orb source. Path must be absolute or relative to the working directory. | ### publish Publish a new version of your orb. This job will produce a development version of an orb by default or will produce a new production version if the $CIRCLE_TAG environment variable is set, and the "pub_type" parameter is set to "production". | Parameter | Type | Default | Description | |---|---|---|---| | `attach_workspace` | boolean | true | If you do not wish to attach the workspace, you may disable this behavior and add your own command or steps via the 'pre-steps' parameter in your workflow. This will attempt to attach the workspace at the path specified by the "orb_dir" parameter. It is expected that the workspace will contain 'orb_source.tar.gz' which should contain one or more orb source files. The tar file will be extracted to the "orb_dir" path. | | `checkout` | boolean | false | If you do not wish to checkout the source code, you may disable this behavior. Replace the checkout and add your own command or steps via the 'pre-steps' parameter in your workflow. | | `circleci_api_host` | string | https://circleci.com | Host URL of CircleCI API. If you are using CircleCI server, this value should be set. | | `circleci_ip_ranges` | boolean | false | Enables jobs to go through a set of well-defined IP address ranges. | | `circleci_token` | env_var_name | CIRCLE_TOKEN | Enter the name of the environment variable containing your CircleCI API Token. This token must have production publishing scope (organization owner). Never directly enter the value of any secret tokens in your config. | | `dev_tags` | string | dev:${CIRCLE_SHA1},dev:alpha | A comma separated list of development version tags to create. These tags are created by default, unless a production version is being published. | | `enable_pr_comment` | boolean | true | If true, a comment will be added to the PR when the orb is published for both development and production orbs. For GitHub users, a $GITHUB_TOKEN environment variable must be set. | | `executor` | executor | default | The executor to use for this job. By default, this will use the "default" executor provided by this orb. | | `github_token` | env_var_name | GITHUB_TOKEN | For GitHub users with "enable_pr_comment" enabled, the GitHub API token must be set. Use this parameter in the event you need to set a custom environment variable name other than the default. | | `orb_dir` | string | dist | Directory containing packed orb source. Path must be absolute or relative to the working directory. Should match the "output_dir" of the "pack" job. | | `orb_file_name` | string | orb.yml | The orb output file name. The orb will be named this value in the output directory. Should match the "orb_file_name" of the "pack" job. | | `orb_name` | string | | The version-less orb slug, e.g. "circleci/orb-tools" | | `pr_comment_graphql_url` | string | https://api.github.com/graphql?= | The url used for GitHub graphql queries when adding comments to pull requests. | | `pub_type` | enum | dev | Select the publishing type. Available options are "dev" and "production". If "production" is selected, the orb will be published to the orb registry only if the $CIRCLE_TAG environment variable is set. Publishing will be skipped otherwise. If "dev" is selected, two tags will be created: "dev:alpha" and "dev:". | | `release_environment` | string | | Enables tracking of the orb release in a defined CircleCI Release's environment. Passing in no environment name will disable tracking. | | `tag_pattern` | string | ^v[0-9]+\.[0-9]+\.[0-9]+$ | A Regular Expression to compare against `$CIRCLE_TAG` when publishing a production version of an orb. Your tag must include a full semantic version number, which will be used to automatically version the published orb. Ensure you CircleCI config is also properly configured to trigger for this tag pattern. It is recommended to prefix or suffix around this pattern: '[0-9]+\.[0-9]+\.[0-9]+'. | | `vcs_type` | enum | | The VCS type. Required to be passed in as a parameter for compatibility. Should be configured automatically by the Orb Development Kit. | ### review Automatically reviews your orb for best practices and produces JUnit test reports which are natively displayed in the CircleCI UI. The "Review" job checks against a suite of "RC" review checks, and if an opportunity for improvement is found, a suggestion with links to the relevant documentation is made. | Parameter | Type | Default | Description | |---|---|---|---| | `checkout` | boolean | true | If you do not wish to checkout the source code, you may disable this behavior. Replace the checkout and add your own command or steps via the 'pre-steps' parameter in your workflow. | | `circleci_ip_ranges` | boolean | false | Enables jobs to go through a set of well-defined IP address ranges. | | `exclude` | string | | A comma separated list of "RC" review check codes to explicitly ignore. Each review check has an associated "RC" code that can be identified to skip in future tests. If a review check fails, the "RC" code will be included in the output. Example: "RC001,RC002" | | `executor` | executor | python | The executor to use for this job. By default, this will use the "python" executor provided by this orb. | | `max_command_length` | integer | 64 | The maximum length of a command (RC009). This is used to check for commands that are too long. Commands longer than this will fail the review. | | `orb_name` | string | | The reference name of the orb to be injected in the config, no namespace or version number. e.g. "orb-tools". This is required for RC011. RC011 will be skipped if this is not set. | | `source_dir` | string | src | Path to the orb source. Path must be absolute or relative to the working directory. | ## Executors ### default The circleci-cli Docker image, which includes the CircleCI CLI executable. | Parameter | Type | Default | Description | |---|---|---|---| | `resource_class` | enum | medium | Configure the executor resource class | | `tag` | string | latest | What version of the CircleCI CLI Docker image? For full list, see https://hub.docker.com/r/circleci/circleci-cli/tags | ### python An Ubuntu based image built by CircleCI with CI/CD in mind. This image contains basic tools and the Python runtime. | Parameter | Type | Default | Description | |---|---|---|---| | `resource_class` | enum | medium | Configure the executor resource class | | `tag` | string | 3.11 | What version of the cimg/python image? For full list, see https://circleci.com/developer/images/image/cimg/python | ## Examples ### step1_lint-pack The Orb-Tools orb is typically configured automatically by the Orb Development Kit. After initializing a new orb, this is the configuration file that will be automatically loaded. This configuration uses "Dynamic Config" with two different configuration files. In this example, we will see only the first `config.yml` file. This config breaks our orb's CI pipeline into two workflows, "test-pack", and "test-deploy". "test-pack" will lint, shellcheck, and review our orb, before triggering the "test-deploy" workflow with the orb injected for e2e testing. See the list of jobs for a detailed description of each job. "test-deploy" is found in the `./circleci/test-deploy.yml` file. See step 2 for more information. ```yaml version: '2.1' setup: true orbs: orb-tools: circleci/orb-tools@12.3 shellcheck: circleci/shellcheck@3.4.0 workflows: lint-pack: jobs: - orb-tools/lint: filters: tags: only: /.*/ - orb-tools/pack: filters: tags: only: /.*/ - orb-tools/review: filters: tags: only: /.*/ orb_name: - shellcheck/check: exclude: SC2148,SC2038,SC2086,SC2002,SC2016 filters: tags: only: /.*/ - orb-tools/continue: filters: tags: only: /.*/ orb_name: pipeline_number: << pipeline.number >> requires: - orb-tools/lint - orb-tools/review - orb-tools/pack - shellcheck/check vcs_type: << pipeline.project.type >> ``` ### step2_test-deploy After linting and shellchecking the orb is injected into this config dynamically by the "continue" job and triggered. The orb is purposefully not imported here, though it is referenced in the config, it will be dynamically injected. With the orb loaded, we can run "integration tests" by executing our orbs commands and jobs and validating their output. Finally, if the commit has been tagged (ex v1.0.0), we can publish the orb to a production version. For advanced usage, see the full docs linked in the "Homepage" url above. ```yaml version: '2.1' orbs: : {} orb-tools: circleci/orb-tools@12.3 jobs: command-tests: docker: - image: cimg/base:current steps: - checkout - /my_command - /my_command_2 workflows: test-deploy: jobs: - command-tests: filters: tags: only: /.*/ - /my-job: filters: tags: only: /.*/ - orb-tools/pack: filters: tags: only: /.*/ - orb-tools/pack: filters: tags: only: /.*/ requires: - command-tests - /my_job - orb-tools/publish: context: - orb-publishing-context filters: branches: ignore: /^pull/[0-9]+/ tags: ignore: /^v[0-9]+\.[0-9]+\.[0-9]+$/ name: publish_dev_test orb_name: / pub_type: dev requires: - orb-tools/pack vcs_type: <> - orb-tools/publish: context: - orb-publishing-context filters: branches: ignore: /.*/ tags: only: /^v[0-9]+\.[0-9]+\.[0-9]+$/ orb_name: / pub_type: production requires: - orb-tools/pack vcs_type: <> ```