Using pipeline parameters

Hi all, I feel like I’ve got a fundamental misunderstanding of the purpose of pipeline parameters, and perhaps more of the CircleCI product.

A common thing that I did with Jenkins was have a job that, when run manually, would require selecting a parameter before the build.

This was handy for things like:

  • redeploying a specific version
  • running one of a number of Ansible playbooks
  • deploying to a particular environment

From what I understand, pipeline parameters (as distinct from orb parameters, or job parameters) are intended for the same purpose. In fact the API documentation seems to suggest that this is possible.

Furthermore, pipeline parameters don’t require a default option. The documentation specifically says:

If not present, the parameter is implied to be required.

Required where? I can’t find anywhere to actually use these.

When I pushed a pipeline with a parameter with no default, I expected to get the option to input this, but instead I was met with an error message about an invalid configuration, despite this being a documented as valid. When I added a default, rather than getting the option to run a pipeline with a specific parameter, CircleCI just unconditionally builds with the default every time.

From all of this, I feel like my mental model of CircleCI’s abilities does not align with the reality. Given that my mental model is informed by the documentation, API schema, data model, and UI, this puts me in a strange place when planning usage of the product, one where I have to second-guess everything I’m told about it.

Some clarity from the product team would be greatly appreciated.

Hello @danpalmer!

Pipeline parameters actually behave similarly to how templating languages like Jinja2 or Mustache do - The << pipeline.parameters.parameter_name >> entry is replaced by the value of the parameter within the configuration file itself.
This is typically used in conjunction with the API to pass values along to the configuration, and there isn’t currently a way to define these within CircleCI itself beyond the default value of the parameter.
If the default value is missing, and it’s not passed along via the API, we consider the value required, and will fail the job since it isn’t present.
Happy to answer any other questions you might have :slight_smile:

Hi @danpalmer,

If I understand you correctly you want to run specific parts of a pipeline via the API, depending on paramters you provide in the API call. This is possible using what we call Conditional Workflows, documented here: Pipeline values and parameters - CircleCI

I hope this helps!


Hi @stig @gmemstr I have no problem to pass parameters via API to trigger the pipeline. However, does CircleCI has a way to let users to manually run the pipeline with those configurations in dashboard UI? So we can let non technical users to trigger the jobs with some dynamic configuration.

Yes, we offer that functionality on our pipelines page. Select the project and branch, and click the “Run Pipeline” button in the top-right corner. You’ll get an option to add parameters & submit the request.

1 Like

Thanks @stig that works as expected! :100:

Can you elaborate on how to get this option? I do have that ‘Add Parameters (optional)’ section but my colleagues don’t, their ‘Run pipeline’ dialog only has buttons. We can of course use the API, but having the option to do that in UI would indeed be important as it’ll make running secondary pipelines easy enough for us to stop using manual approval jobs for optional workflows.

Hi @sparhomenko, let me dig into that. This is a recent feature, so maybe it’s not rolled out to all users yet.

Hi @sparhomenko, the feature currently isn’t rolled out to all users. We currently expect it to roll out in early August if everything goes according to plan.

1 Like

Hi @sparhomenko the feature has now been rolled out to all.

I came across this thread and don’t feel the original question from @danpalmer was properly answered.

The original question was about the default value being omitted from a top level pipeline parameter, e.g:

    type: boolean
    default: false
    type: string

Like @danpalmer, from reading the documentation I had expected this to be allowed but it isn’t - the config.yml file fails to validate with the following error:

[#/parameters/my_required_param] required key [default] not found

Is there no way of making a parameter mandatory when invoking a build via “Trigger Pipeline”? Ideally all such “required” parameters would be pre-populated in the dialog box:


I came across this thread and had the same question that stec00 has: is there any way to mark a parameter as required so that, when a user manually trigger a pipeline through the CircleCI web app, the user is forced to enter a non-blank value for the parameter? Something like

    type: string
    required: true

No, you can only set a default.

As you can set a default you could set it to a value that you can later check for and then end the workflow with a message stating that a valid value must be passed into the workflow.

1 Like