CI/CD

Use the Truss Push GitHub Action to deploy and validate Truss models or Chains from GitHub. Run it on pull requests to test a temporary deployment, or on merges to release a model to an environment.

What happens during a run

Depending on the deployment type and inputs, a run can include these steps:

Load config: For models, reads config.yaml from the Truss directory and extracts model_metadata.example_model_input for the predict step. The predict-payload input overrides that value. For Chains, detects the entrypoint class from the .py file.
Deploy: Pushes the model or Chain to Baseten. For a model, the action streams build logs into the GitHub Actions output. For a Chain, it prints deployment status changes and chainlet log URLs. For models, the action also names each deployment from git context: PR-42_abc1234 for pull requests or abc1234 for direct pushes. Override the generated name with deployment-name.
Predict: If the action resolves a payload that it doesn’t skip, sends a predict request and reports latency. For streaming models when the payload includes "stream": true, it reports time-to-first-byte, token count, and tokens per second.
Cleanup: If cleanup: true, deactivates the newly created deployment. Set cleanup: false when a model workflow deploys to an environment or when you want to inspect a deployment manually.

The job summary includes the time spent waiting for the deployment to become active after the push call returns. If prediction runs, the summary also includes predict metrics. A model run includes a direct link to its deployment logs. For a Chain, use the chainlet log URLs in the deploy output.

Prerequisites

Store your Baseten API key as an encrypted secret named BASETEN_API_KEY in your repository or organization settings. See API keys for how to generate one.

Deploy with the Baseten CLI

The GitHub Action wraps deploy, predict validation, and cleanup in one step. If you only need to deploy, run the Baseten CLI directly in your workflow. The CLI reads your API key from the BASETEN_API_KEY environment variable, and --wait blocks the step until the deployment is active so a failed deploy fails the job:

.github/workflows/deploy.yml

name: Deploy to production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install the Baseten CLI
        run: brew tap basetenlabs/baseten && brew install baseten

      - name: Push the model
        env:
          BASETEN_API_KEY: ${{ secrets.BASETEN_API_KEY }}
        run: baseten model push --dir ./my-model --environment production --wait

For the full push surface, see model push. To add predict validation and cleanup to a CLI-based flow, see Validate on pull request for the Action-based equivalent.

Deploy to an environment on merge

Deploy a validated model to a specific environment every time code merges to main. Create .github/workflows/deploy.yml and add the following:

.github/workflows/deploy.yml

name: Deploy to production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: basetenlabs/action-truss-push@v0.1.2
        with:
          truss-directory: "./my-model"
          baseten-api-key: ${{ secrets.BASETEN_API_KEY }}
          environment: "production"
          cleanup: false

Setting environment publishes the model deployment to the specified environment. Setting cleanup: false keeps the deployment active so it can serve traffic. For a model deployed to a regional environment, add regional-environment: true to the action’s with block. The action then sends its predict validation request through the regional endpoint.

Validate on pull request

Catch model regressions before they reach production. The action deploys, runs a predict request, and tears down the deployment inside the PR check. Create .github/workflows/validate-model.yml and add the following:

.github/workflows/validate-model.yml

name: Validate model

on:
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: basetenlabs/action-truss-push@v0.1.2
        with:
          truss-directory: "./my-model"
          baseten-api-key: ${{ secrets.BASETEN_API_KEY }}

The action reads model_metadata.example_model_input from your config.yaml to build the predict request. With the default (cleanup: true), the deployment is deactivated after validation, so no resources are left running.

Deploy a Chain

Deploy a Baseten Chain from a Python source file. The action auto-detects Chains when truss-directory points to a .py file:

- uses: basetenlabs/action-truss-push@v0.1.2
  with:
    truss-directory: "./chains/my_chain.py"
    baseten-api-key: ${{ secrets.BASETEN_API_KEY }}
    model-name: "my-rag-chain"
    cleanup: false
    predict-payload: '{"query": "What is Baseten?"}'

For Chains, provide the predict payload explicitly with predict-payload because there’s no config.yaml to read example input from.

In v0.1.2, the environment inputs don’t promote a Chain. Leave regional-environment set to false to validate the new Chain deployment through its deployment-specific endpoint. See the regional-environment input for regional validation behavior.

Deploy multiple models

Use a matrix strategy to deploy each model in your repository as a separate job. Create .github/workflows/deploy-all.yml and add the following:

.github/workflows/deploy-all.yml

name: Deploy models

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        model:
          - path: models/text-classifier
          - path: models/image-generator
          - path: models/embeddings
    steps:
      - uses: actions/checkout@v4

      - uses: basetenlabs/action-truss-push@v0.1.2
        with:
          truss-directory: ${{ matrix.model.path }}
          baseten-api-key: ${{ secrets.BASETEN_API_KEY }}
          environment: "production"
          cleanup: false

Each matrix entry runs as a separate job. If one model fails, the others still deploy.

Custom predict validation

Override the default predict payload when your model needs a specific input shape that differs from model_metadata.example_model_input:

- uses: basetenlabs/action-truss-push@v0.1.2
  with:
    truss-directory: "./my-model"
    baseten-api-key: ${{ secrets.BASETEN_API_KEY }}
    predict-payload: '{"prompt": "Hello, world!", "max_new_tokens": 128}'
    predict-timeout: 60

The action skips the predict step when the resolved JSON value is missing, null, false, 0, an empty string (""), an empty object ({}), or an empty array ([]). A skipped predict step doesn’t validate the deployment.

Deploy with labels

Attach metadata labels to track model deployments in your CI pipeline:

- uses: basetenlabs/action-truss-push@v0.1.2
  with:
    truss-directory: "./my-model"
    baseten-api-key: ${{ secrets.BASETEN_API_KEY }}
    labels: '{"team": "ml-platform", "triggered-by": "ci"}'

For more information, see Label deployments.

Override model name

Set a custom model name instead of using the name from config.yaml:

- uses: basetenlabs/action-truss-push@v0.1.2
  with:
    truss-directory: "./my-model"
    baseten-api-key: ${{ secrets.BASETEN_API_KEY }}
    model-name: "my-custom-name"

Use action outputs

The action exposes outputs you can reference in downstream steps. This example posts the deploy time as a PR comment:

steps:
  - uses: actions/checkout@v4

  - uses: basetenlabs/action-truss-push@v0.1.2
    id: deploy
    with:
      truss-directory: "./my-model"
      baseten-api-key: ${{ secrets.BASETEN_API_KEY }}

  - name: Comment on PR
    if: github.event_name == 'pull_request'
    uses: actions/github-script@v7
    with:
      script: |
        github.rest.issues.createComment({
          owner: context.repo.owner,
          repo: context.repo.repo,
          issue_number: context.issue.number,
          body: `Post-push wait to active: ${{ steps.deploy.outputs.deploy-time-seconds }} seconds. Status: ${{ steps.deploy.outputs.status }}`
        })

See the full list of inputs and outputs in the Truss Push GitHub Action reference.

Troubleshooting

`deploy_timeout`

The default timeout is 45 minutes, which accommodates large builds like TRT-LLM. For smaller models, reduce deploy-timeout-minutes to fail faster. If your model needs more time, increase the value.

`deploy_failed`

Verify the BASETEN_API_KEY secret first. For a model, check config.yaml and expand the build output in the GitHub Actions UI. For a Chain, check the source file and follow the chainlet log URLs in the deploy output.

`predict_failed`

Verify the predict payload shape matches what your model expects. Check model_metadata.example_model_input in config.yaml, or override it with predict-payload. For Chains, provide the predict payload explicitly.

`cleanup_failed`

The deployment may still be running. Deactivate it manually from the Baseten dashboard.

429 too many requests

The action calls Management API endpoints that are rate limited per API key. Matrix jobs that fan out across many models can exceed the per-endpoint limits. See Management API rate limits for thresholds and backoff guidance.

No predict output

The action skips prediction when the resolved JSON value is missing, null, false, 0, an empty string (""), an empty object ({}), or an empty array ([]). For a model, add an example input to config.yaml that isn’t one of these values. For a Chain, set predict-payload to a value that the action doesn’t skip.

`Team selection required but running in a non-interactive context`

For a model workflow, your API key has access to multiple teams and Truss can’t infer a single target team without a prompt. Pass the team explicitly with the team input on the action. If you invoke truss push directly, use --team <name>.

- uses: basetenlabs/action-truss-push@v0.1.2
  with:
    truss-directory: "./my-model"
    baseten-api-key: ${{ secrets.BASETEN_API_KEY }}
    team: "ml-platform"

See Deploy to a team for the team-resolution rules. Requires Truss 0.18.3 or later. The team input in action-truss-push@v0.1.2 applies to models only. For a Chain workflow, use an API key that resolves to the intended team without an interactive selection.

Next steps

Rolling deployments

Promote validated deployments to production without downtime.

Environments

Manage staging and production environments for your models.

Manage deployments

Scale, promote, and clean up deployments from the Baseten CLI or Management API.

Get started

Model APIs

Inference

Training

Development

Deployment

Engines

Model Labs

Organization

Hosting options

Observability

Troubleshooting

What happens during a run

Prerequisites

Deploy with the Baseten CLI

Deploy to an environment on merge

Validate on pull request

Deploy a Chain

Deploy multiple models

Custom predict validation

Deploy with labels

Override model name

Use action outputs

Troubleshooting

`deploy_timeout`

`deploy_failed`

`predict_failed`

`cleanup_failed`

429 too many requests

No predict output

`Team selection required but running in a non-interactive context`

Next steps

Rolling deployments

Environments

Manage deployments

​What happens during a run

​Prerequisites

​Deploy with the Baseten CLI

​Deploy to an environment on merge

​Validate on pull request

​Deploy a Chain

​Deploy multiple models

​Custom predict validation

​Deploy with labels

​Override model name

​Use action outputs

​Troubleshooting

​deploy_timeout

​deploy_failed

​predict_failed

​cleanup_failed

​429 too many requests

​No predict output

​Team selection required but running in a non-interactive context

​Next steps

Rolling deployments

Environments

Manage deployments

What happens during a run

Prerequisites

Deploy with the Baseten CLI

Deploy to an environment on merge

Validate on pull request

Deploy a Chain

Deploy multiple models

Custom predict validation

Deploy with labels

Override model name

Use action outputs

Troubleshooting

`deploy_timeout`

`deploy_failed`

`predict_failed`

`cleanup_failed`

429 too many requests

No predict output

`Team selection required but running in a non-interactive context`

Next steps