DOCSEARCHbyAlgolia
Submit Docs

PandaCI Documentation

website·Indexed 31 days ago

https://pandaci.com

A CI/CD platform that uses TypeScript for defining workflows. Documentation covers the platform's core concepts including runners, secrets, and workflow environments, as well as TypeScript syntax for configuring jobs, Docker tasks, exec steps, and workflow triggers. Includes guides for installing packages, sending Slack notifications, and setting up CI/CD for Node.js and Python projects.

Tokens
7.4K
Snippets
39
Records
63
Agent score
60%

What's inside PandaCI

  1. Define CI/CD workflows using TypeScript with PandaCI

    PandaCI replaces declarative YAML configurations with a 'CI/CD as Code' approach using TypeScript or JavaScript. This allows developers to use standard programming constructs like variables, loops, and conditionals, and leverage the npm ecosystem directly within their workflow definitions.
    import { docker, $ } from "@pandaci/workflow";

docker("ubuntu:latest", async () => {
    await $`echo "Hello, World!"`;
});

  2. Manage and use Secrets in PandaCI workflows

    Secrets in PandaCI are used to securely store sensitive data such as API keys and passwords. They are automatically loaded as environment variables at the workflow level. To use a secret within a specific job, you must pass it as an argument to the command. Note that because secrets are loaded as environment variables, any user with permission to edit the workflow could potentially expose them.

  3. Understand PandaCI Workflow and Job execution architecture

    PandaCI uses a tiered execution model to build and test code:

    1. Workflow Runner: An isolated VM running a Go agent that orchestrates the overall workflow and manages communication between services. It performs a shallow clone of the repository (latest commit only).
    2. Job Runner: Provides isolated environments for executing workflow steps. Like the workflow runner, it performs a shallow clone of the repository, which is then mounted into any Docker tasks to ensure file consistency across tasks.

  4. Execute shell commands using Exec Step

    The Exec Step allows you to execute shell commands within a task (such as a Docker task). It uses the $ tagged template literal and returns a promise that resolves when the command completes. Commands are automatically escaped to prevent command injection.
    import { docker, $ } from "jsr:@pandaci/workflow";

docker("ubuntu:latest", () => {
  $`echo "Hello, world!"`;

  const output = $`ls`.text();
});

  6. Invite team members to a PandaCI organization

    PandaCI allows unlimited organization members on all plans. To invite a team member, navigate to the Members page within your organization and click the Invite Member button located in the top right corner.

    • If the invitee is an existing PandaCI user, they are added to the organization automatically.
    • If the invitee is not a PandaCI user, they will receive an email invitation which must be accepted within 3 days.

  7. Create a TypeScript workflow in PandaCI

    To create a workflow in PandaCI, create a file with the .workflow.ts extension inside the .pandaci directory. PandaCI uses Deno to execute these workflows. You can create multiple workflow files within the .pandaci directory to organize your project.
    // Example file path: .pandaci/hello-world.workflow.ts
import { docker, $, job, env } from "jsr:@pandaci/workflow";

// Define a docker task on a 4-core machine
docker("ubuntu:latest", { name: "hello world" }, () => {
  // Runs a shell command using the $ template literal
  $`echo "Hello, world! from branch: ${env.PANDACI_BRANCH}"`;
});

// Define a job with a specific runner
job("Job 2", { runner: "ubuntu-2x" }, async () => {
  let files = '';
  await docker("ubuntu:latest", async () => {
    // Run command in a specific directory and capture output as text
    files = await $`ls`.cwd(".pandaci").text();
  });
  docker("ubuntu:latest", () => {
    // Share data between tasks or jobs
    $`echo "files from another task: ${files}"`;
  });
});

  9. Install Deno for PandaCI local development

    To set up a local development environment for TypeScript workflows in PandaCI, install the Deno CLI and related tools. Installation instructions are provided in the official Deno installation guide.

  10. Create and run a Job in PandaCI

    Jobs are isolated machines that provide a runner and context for your tasks. If you run tasks without wrapping them in a job, PandaCI automatically creates a default job using the "ubuntu-4x" runner.
    import { job } from "jsr:@pandaci/workflow"

// Simple job (uses default ubuntu-4x runner)
await job("A very cool job", () => {
  // ...
})

// Job with a custom runner
await job("A very cool job", { runner: "ubuntu-8x" }, () => {
  // ...
})

  11. Set up a Slack App for PandaCI notifications

    To send notifications from PandaCI, you must create a Slack app with the chat:write bot permission.

    1. Create a new app at the Slack API page.
    2. Grant the chat:write scope (or use the provided manifest).
    3. Install the app to your workspace.
    4. Copy the Bot User OAuth Token and save it as a PandaCI project variable named SLACK_BOT_TOKEN.
    5. (Optional) Get the Channel ID from the channel details modal and save it as SLACK_CHANNEL_ID.
    6. Ensure the Slack app is added to the target channel.
    {
    "_metadata": {
        "major_version": 1,
        "minor_version": 1
    },
    "display_information": {
        "name": "PandaCI Slack App",
        "description": "Sends workflow notifications from the greatest CI/CD platform"
    },
    "features": {
        "bot_user": {
            "display_name": "PandaCI Bot",
            "always_online": true
        },
        "app_home": {
            "home_tab_enabled": false
        }
    },
    "oauth_config": {
        "scopes": {
            "bot": [
                "chat:write"
            ]
        }
    }
}

  12. Create a global exec instance with custom defaults

    You can create a reusable 'global' exec instance by calling the $ function without a string or by passing a configuration object. This is useful for setting a consistent working directory across multiple commands.
    // Using .cwd() method
const buildExec = $.cwd("./build");
buildExec`ls`;

// Using configuration object
const testExec = $({ cwd: "./test" });
testExec`ls`;