Setting up GitHub Actions

Use GitHub Actions to build and deploy modules with the Cognite Toolkit. This guide covers the starter workflows from cdf repo init. GitHub runs workflow files in .github/workflows/ after you commit them. Prerequisites:

A GitHub repository for the Cognite Toolkit project
A Cognite Data Fusion (CDF) project with authentication configured
The Cognite Toolkit installed and configured locally

When you promote across dev, test, and prod, use the GitHub Actions workflows that the Foundation deployment pack generates. It creates one workflow per environment, validates pull requests with cdf build (no credentials), and deploys production from a GitHub release tagged vX.Y.Z.This guide uses cdf repo init, which writes starter dry-run and deploy workflows for one environment. If the Foundation pack is installed, run python modules/common/cdf_project_foundation/scripts/generate_actions.py instead. Follow the generated docs/FOUNDATION_CICD.md, then complete Add environment variables and secrets.

Add workflows to your repository

Generate workflow files

In a terminal, run these commands and select GitHub Actions as the CI/CD provider:

git switch -c add-gh-actions
cdf repo init

The command creates example deploy and dry-run workflows in .github/workflows. Adapt the generated files to your branches and CDF environments. Pin the Cognite Toolkit version to [modules].version in cdf.toml.

Adapt and commit the workflows

Use the on: section to specify when each workflow should run. The starter deploy workflow runs on every push to main. Protect main so that changes go through a pull request.You can add workflow_dispatch to trigger a workflow manually. See GitHub’s Events that trigger workflows.Use cdf build or cdf deploy --dry-run on pull requests to validate modules before merge.The environment property on a job lets you keep different variables and secrets for each CDF environment (for example, dev, test, prod). You can add flags such as --verbose to cdf build and cdf deploy.

git add .github/workflows
git commit -m "Add Cognite Toolkit GitHub workflows"
git push -u origin add-gh-actions

Create a pull request to merge the branch into main.

Add environment variables and secrets

Set up environment variables and secrets

To use the GitHub Actions, set up environment variables and secrets in your repository settings.

GitHub repository environment variables and secrets

The workflow reads these values. Environment variables (for example ${{ vars.CDF_CLUSTER }}) are visible to anyone with access to the repository. Secrets (for example ${{ secrets.IDP_CLIENT_SECRET }}) are encrypted and only available to the workflow.A standard client credentials flow requires these environment variables and secrets:Variables

CDF_CLUSTER
CDF_PROJECT
LOGIN_FLOW (client_credentials)
IDP_CLIENT_ID
IDP_TENANT_ID
IDP_TOKEN_URL (only if you are not using Microsoft Entra ID)

Secrets

IDP_CLIENT_SECRET

View workflow run details

You can see the status of each run and step in the Actions tab of your repository. Open a step to see the logs.

GitHub Actions run logs for a Cognite Toolkit workflow

​Add workflows to your repository

​Add environment variables and secrets

​View workflow run details

Add workflows to your repository

Add environment variables and secrets

View workflow run details