Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Publish a Pipeline to a ServiceBeta

Beta
This is coming — this page describes a feature that's still being rolled out and may not be available to you yet.

Publish a pipeline version to a service to make it available to external callers in a stable endpoint. You can publish the same pipeline version to multiple services. One service can only serve one pipeline version.

About This Task​

Services let you separate your work in progress from what's live in production. Once you publish a pipeline version to a service, external callers can use it there in a reliable environment, while you can continue to iterate on the pipeline in the Builder. Your services live in Gateway, where you can manage them.

To learn more, see Gateway.

Prerequisites​

  • A pipeline version ready to be published.
  • A pinned Haystack version in the pipeline version you publish. Pin it in the pipeline's settings. For details, see Pin the Haystack Version.
  • Read and write permissions to services.

Publish a Pipeline to a Service​

  1. In the navigation, go to Pipelines and click the name of the pipeline you want to publish.

  2. In Builder, click Publish. This publishes the current version. To publish a previous version, restore it first.

  3. Choose how you want to publish and move to the next step.

    • Create a service and publish to it.
    • Publish to an existing service.
    Deploying a Pipeline without a Service

    This just deploys the pipeline without any service. This option is not recommended for production use where external apps call your pipeline. Every time you deploy a new pipeline version, the endpoint URL changes. Deploying a pipeline is required to test it in the Playground. For production use, we recommend publishing it to a service, where the endpoint URL stays the same, regardless of the pipeline version you publish.

  4. If you're publishing to a new service:

    1. Give your service a name and, optionally, a description and tags to easily identify it. You can add up to three tags to help you group and filter your services later.

    2. Configure the hosting settings for the service.

      Hosting Settings

      Hosting determines

      the minimum and maximum number of replicas that must be available for the service and idle timeout. Idle timeout is the period of inactivity after which the service becomes inactive to save resources. You can update these settings at any time from the Service Details page.

      Choose an option under Hosting:

      • High demand: Choose this option for production pipelines that require high availability and scalability.
      • Low demand: Choose this option for testing and pipelines that are not used frequently.
      • Custom: Configure your own hosting settings.

    3. Review the pipeline version, update the message to describe the changes, and click Create service. The service is starting. Wait until it's ready to serve queries. You can view it in Gateway.

  5. If you're publishing to an existing service:

    1. Choose the service from the list and click Continue to comparison.
    2. Review the pipeline version, update the message to describe the changes, and click Publish. The pipeline version is published to the service and the service is starting. Wait until it's ready to serve queries. You can view it in Gateway.
    3. To follow the rollout, click Versions in Builder. The version you published shows a spinner and a Publishing to N services tag, where N is the number of services rolling out to it. The version that currently serves keeps its service tag. When the rollout finishes, the new version shows the service tag and serves the service's callers.

Troubleshoot a Publish That Is Rejected for a Missing Haystack Version​

A service runs on the Haystack version that its pipeline configuration pins. If the pipeline version you publish doesn't pin one, the platform rejects the publish, and the publish step shows a notice that no Haystack version is pinned. This also applies to new versions of existing services.

To fix it:

  1. Click Pipeline Settings in the notice, or open the pipeline's Settings from Pipelines.
  2. Choose a version from the Haystack Version list. This saves a haystack-ai dependency to the pipeline configuration. If you edit the YAML directly, add haystack-ai==<version> under dependencies.
  3. Publish the pipeline version again.

If you publish with the REST API, a revision request without a pinned version returns a 422 error. Add the pin to the config_yaml in your request and retry. Revisions built from code are not affected, because a code build pins its environment in its code bundle.

Publish to a Service That Has No Pipeline Yet​

When you create a service without a pipeline, its Overview tab shows a Publish your first pipeline section with two options side by side. Pick the one that matches how you work: publish a pipeline you built in the platform, or publish a Haystack pipeline or agent from your machine with a coding agent or the CLI. Either way, you publish to this service only.

  1. In the navigation, click Gateway and click the name of the service.
  2. On Overview, choose how to publish:
    • Publish from the platform: Click Publish a pipeline, then choose the pipeline and version to publish. If you haven't built a pipeline yet, click No pipeline yet? Build one first to go to Pipelines.
    • Use the CLI or a coding agent: Select With a coding agent or With the CLI, as described below.

Publish with a Coding Agent​

Use this option if you want a coding agent, such as Claude Code or Cursor, to do the work. The prompt tells the agent to install the Haystack Enterprise CLI, deploy your local Haystack pipeline to this service, and check that it's serving. It's pre-filled with your workspace, the service name, and the service's deployment ID, so the agent publishes to this service and doesn't create a new one.

  1. Under Use the CLI or a coding agent, select With a coding agent.
  2. Click the copy icon to copy the prompt.
  3. Paste the prompt into your coding agent and run it from the project that contains your pipeline.
  4. When the agent asks you to log in, complete the login in your browser. You only need to log in once.

Publish with the CLI​

Use this option if you prefer to run the commands yourself. Each step shows a command you can copy.

  1. Under Use the CLI or a coding agent, select With the CLI.
  2. Under Install the CLI, copy and run the install command.
  3. Under Log in, copy and run haystack-enterprise login. This opens your browser so you can pick a workspace. On a remote machine, add --device.
  4. Under Publish to this service, copy and run the command. Replace <your_pipeline.py> with the Python file that defines your pipeline or agent. The command adds a new version to this service. A different service name would create a new service.
  5. Under Check that it is serving, copy and run the command to confirm the service is serving.

Only Haystack pipelines and agents are supported. For all CLI options, see Deploy a Pipeline.

Record Where Pushed Code Came From​

When you push a revision to a service from code, for example from a script or a CI job, you can attach information about its origin. This helps your team trace a running revision back to the commit and file it was built from.

To attach origin information, add the optional source_metadata object to the request that creates the revision. All keys are optional:

  • git: The repository and commit. It holds repo (for example, github.com/org/repo), branch, sha, and dirty. Set dirty to true when the working tree had uncommitted changes.
  • file: The repository-relative path of the source file.
  • ci: Set to true when an automated pipeline made the push.
  • custom: A free-form JSON object for your own metadata, such as a team name or a ticket ID.

The platform stores this information with the revision and returns it as source_metadata in the revision response, next to the code build details.

Keep these points in mind:

  • The platform doesn't verify the values. They are what the client reports.
  • The platform ignores any other keys in source_metadata.
  • The request fails with a validation error if a value is too long. The limits are 300 characters for repo, 255 for branch, 64 for sha, and 1,024 for file. The custom object can be up to 8,192 characters when serialized as JSON, and it can't contain NaN values. Shorten the value and send the request again.
  • The information doesn't change the revision's config hash, and it never reaches the running service.

What To Do Next​

  • Click the service name to view and update its details.
  • Publish a pipeline version to the service.
  • Create an API key for the service to use it in your code.
  • Call the service from your app, an OpenAI-compatible client, or an MCP client.