GitLab CI/CD

---

Chalk provides official support for GitLab CI/CD. You can install the Chalk CLI and create deployments (preview and production) using GitLab CI/CD jobs.

---

​

Installing the Chalk CLI

You will need to create a Chalk token from the settings page of your dashboard and store the resulting client ID and secret as GitLab CI/CD Variables.

The Chalk CLI reads its credentials and target from environment variables, so a job needs no separate login step. Define these variables:

• CHALK_CLIENT_ID: The Chalk Client ID from the tokens page in your settings (stored as CI/CD variable).
• CHALK_CLIENT_SECRET: The Chalk Client Secret from the tokens page in your settings (stored as masked CI/CD variable).
• CHALK_VERSION (optional): The version of chalk to install, defaulting to latest.
• CHALK_API_SERVER (optional): If you’re using a self-hosted deployment, the API host where Chalk is hosted.
• CHALK_ENVIRONMENT (optional): The Chalk environment to use. Your token is typically scoped to a single environment, and you won’t need to use this parameter.

​

Example

install-chalk:
  stage: setup
  image: ubuntu:latest
  before_script:
    - apt-get update && apt-get install -y curl
  script:
    - curl -s -L https://api.chalk.ai/install.sh | sh -s -- "${CHALK_VERSION:-latest}"
    - export PATH="$HOME/.chalk/bin:$PATH"
    - chalk version
  variables:
    # Optional: Version of the Chalk CLI to install. Defaults to `latest`
    CHALK_VERSION: latest

The install script puts the CLI in $HOME/.chalk/bin.

---

​

Deploying to Chalk

You can deploy to Chalk by installing the CLI, as in the section above, and running chalk apply in the same job. --force skips the interactive confirmation, which a CI job can’t answer. See chalk apply for its other flags.

A production deploy checks your features and resolvers before deploying, and the check runs your project’s Python code. The job needs Python and your project’s dependencies, including chalkpy, installed before chalk apply runs. Use the Python version that matches the runtime in your project’s chalk.yaml. The example uses a Python image for this. This job supports the following variables:

• CHALK_CLIENT_ID: The Chalk Client ID from the tokens page in your settings (stored as CI/CD variable).
• CHALK_CLIENT_SECRET: The Chalk Client Secret from the tokens page in your settings (stored as masked CI/CD variable).
• CHALK_BRANCH (optional): By default, Chalk will deploy to your production environment. With this variable, your pipelines will deploy to a Chalk branch.
• CHALK_AWAIT (optional): Should this job block until deployment completes? Defaults to true.
• CHALK_VERSION (optional): The version of chalk to install, defaulting to latest.
• CHALK_API_SERVER (optional): If you’re using a self-hosted deployment, the API host where Chalk is hosted.
• CHALK_ENVIRONMENT (optional): The Chalk environment to use. Your token is typically scoped to a single environment, and you won’t need to use this parameter.

​

Example

stages:
  - deploy

deploy-chalk:
  stage: deploy
  image: python:3.12
  before_script:
    # Your project's dependencies, including chalkpy
    - pip install -r requirements.txt
    - curl -s -L https://api.chalk.ai/install.sh | sh -s -- "${CHALK_VERSION:-latest}"
    - export PATH="$HOME/.chalk/bin:$PATH"
  script:
    - |
      # Deploy to Chalk
      DEPLOY_ARGS="--force --no-spinners"
      if [ -n "$CHALK_BRANCH" ]; then
        DEPLOY_ARGS="$DEPLOY_ARGS --branch=$CHALK_BRANCH"
      fi
      if [ "$CHALK_AWAIT" = "false" ]; then
        DEPLOY_ARGS="$DEPLOY_ARGS --await=false"
      fi
      chalk apply $DEPLOY_ARGS
  variables:
    # Optional: Version of the Chalk CLI to install. Defaults to `latest`
    CHALK_VERSION: latest
    # Optional: Environment to use. Optional for environment-scoped tokens.
    # CHALK_ENVIRONMENT: <environment id>
    # Optional: Used for Hybrid Cloud deployments
    # CHALK_API_SERVER: https://custom.deployment.com/
    # Optional: Deploy to a specific branch instead of production
    # CHALK_BRANCH: feature-branch
    # Optional: Wait for deployment to complete (default: true)
    # CHALK_AWAIT: "false"