### Install Pkl CLI

Source: https://github.com/stefma/pkl-gha/blob/main/README.md

This code snippet shows how to install the Pkl command-line interface (CLI) on macOS using Homebrew. It provides a command for installation and links to the official guide for other platforms.

```bash
brew install pkl
```

--------------------------------

### Compile Pkl Workflows to GitHub Actions YAML using Pkl CLI

Source: https://context7.com/stefma/pkl-gha/llms.txt

Demonstrates how to use the Pkl CLI to compile Pkl workflow files into YAML format suitable for GitHub Actions. It covers installation, compiling single and multiple workflows, and basic validation commands.

```bash
# Install Pkl CLI
brew install pkl  # macOS
# For other platforms: https://pkl-lang.org/main/current/pkl-cli/index.html#installation

# Compile single workflow
pkl eval .github/workflows/ci.pkl -o .github/workflows/ci.yml

# Compile all workflows in directory
pkl eval .github/workflows/*.pkl -o .github/workflows/%{moduleName}.yml

# Project configuration example
cat > PklProject << 'EOF'
amends "pkl:Project"

package {
  name = "my-workflows"
  baseUri = "package://example.com/workflows"
  version = "1.0.0"
}
EOF

# Validate before compilation
pkl eval --expression 'name' workflow.pkl  # Should output workflow name
pkl test                                    # Run tests if configured
```

--------------------------------

### Pkl Matrix Build Strategy for GitHub Actions

Source: https://context7.com/stefma/pkl-gha/llms.txt

Defines a matrix strategy for GitHub Actions workflows using Pkl. This allows for testing across multiple operating systems, Node.js versions, and configurations. It requires the pkl-gha library and specifies checkout, Node.js setup, and build steps.

```pkl
amends "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Workflow.pkl"
import "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Action.pkl"
import "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Context.pkl"

name = "Matrix Build"

on {
  push {
    branches { "main" }
  }
}

jobs {
  ["test"] {
    `runs-on` = "${{ matrix.os }}"
    `timeout-minutes` = 30
    strategy {
      matrix {
        ["os"] = new {
          "ubuntu-latest"
          "macos-latest"
          "windows-latest"
        }
        ["node-version"] = new {
          "16"
          "18"
          "20"
        }
        ["config"] = new {
          new {
            os = "ubuntu-latest"
            runtime = "linux-x64"
          }
          new {
            os = "windows-latest"
            runtime = "win-x64"
          }
          new {
            os = "macos-latest"
            runtime = "osx-x64"
          }
        }
      }
      `fail-fast` = false
      `max-parallel` = 4
    }
    steps {
      (Action.checkout) {
        name = "Checkout code"
      }
      (Action.setupNode) {
        nodeVersion = "\(Context.matrix("node-version"))"
      }
      new {
        name = "Run tests on \(Context.matrix("os"))"
        run = "npm test"
      }
      new {
        name = "Build for \(Context.matrix("runtime"))"
        run = "npm run build --runtime \(Context.matrix("config.runtime"))"
      }
    }
  }
}

```

--------------------------------

### Pkl GitHub Actions Workflow Triggers Configuration

Source: https://context7.com/stefma/pkl-gha/llms.txt

Configures various event triggers for GitHub Actions workflows using Pkl. This example demonstrates triggers for push events (including branches, tags, and paths), pull requests, scheduled jobs, manual dispatch with inputs, and release events. It depends on the pkl-gha library.

```pkl
amends "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Workflow.pkl"

name = "Trigger Examples"

on {
  push {
    branches {
      "main"
      "release/**"
    }
    `branches-ignore` {
      "experimental/**"
    }
    tags {
      "v*.*.*"
    }
    paths {
      "src/**"
      "*.go"
    }
    `paths-ignore` {
      "docs/**"
      "**.md"
    }
  }
  pull_request {
    types {
      "opened"
      "synchronize"
      "reopened"
      "ready_for_review"
    }
    branches {
      "main"
    }
  }
  schedule {
    cron {
      "0 2 * * *"  // Daily at 2 AM
      "0 0 * * 1"  // Weekly on Monday
    }
  }
  workflow_dispatch {
    inputs {
      ["environment"] = new {
        description = "Target environment"
        required = true
        type = "choice"
        options {
          "development"
          "staging"
          "production"
        }
      }
      ["debug"] = new {
        description = "Enable debug mode"
        required = false
        type = "boolean"
        default = "false"
      }
    }
  }
  release {
    types {
      "published"
      "created"
    }
  }
}

jobs {
  ["deploy"] {
    `runs-on` = "ubuntu-latest"
    steps {
      new {
        run = "echo 'Triggered workflow'"
      }
    }
  }
}

```

--------------------------------

### Use Pre-built Actions in Pkl Workflows

Source: https://context7.com/stefma/pkl-gha/llms.txt

Illustrates the use of pre-built, typed wrappers for common GitHub Actions (e.g., checkout, setup-java, setup-go, cache, upload-artifact) within a Pkl-defined workflow. This simplifies the integration of standard actions.

```pkl
amends "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Workflow.pkl"
import "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Action.pkl"

name = "Test with Pre-built Actions"

on {
  push {}
}

jobs {
  ["test"] {
    `runs-on` = "ubuntu-latest"
    steps {
      Action.checkout
      (Action.setupJava) {
        javaVersion = 17
        distribution = "temurin"
        cache = "gradle"
      }
      (Action.setupGo) {
        goVersion = "1.20.2"
        cache = true
      }
      (Action.setupPython) {
        pythonVersion = "3.11"
        cache = "pip"
      }
      (Action.cache) {
        path = "~/.gradle/caches"
        key = "gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle') }}"
      }
      new {
        name = "Build"
        run = "./gradlew build"
      }
      (Action.uploadArtifact) {
        name = "build-artifacts"
        path = "build/libs/"
        retentionDays = 5
      }
    }
  }
}

```

--------------------------------

### Define Reusable GitHub Actions Workflow with Pkl

Source: https://context7.com/stefma/pkl-gha/llms.txt

This Pkl code defines a reusable GitHub Actions workflow named 'Deploy Application'. It specifies inputs for environment and version, optional dry-run, outputs for deployment URL, and requires 'deploy-token' and optional 'api-key' secrets. It includes a 'deploy' job that runs on 'ubuntu-latest' and sets a dummy deployment URL.

```pkl
amends "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Workflow.pkl"

name = "Deploy Application"

on {
  workflow_call {
    inputs {
      ["environment"] = new {
        description = "Deployment environment"
        required = true
        type = "string"
      }
      ["version"] = new {
        description = "Version to deploy"
        required = true
        type = "string"
      }
      ["dry-run"] = new {
        description = "Perform a dry run"
        required = false
        type = "boolean"
        default = "false"
      }
    }
    outputs {
      ["deployment-url"] {
        description = "URL of deployed application"
        value = "${{ jobs.deploy.outputs.url }}"
      }
    }
    secrets {
      ["deploy-token"] {
        description = "Deployment token"
        required = true
      }
      ["api-key"] {
        description = "API key"
        required = false
      }
    }
  }
}

jobs {
  ["deploy"] {
    `runs-on` = "ubuntu-latest"
    outputs {
      ["url"] = "${{ steps.deploy.outputs.url }}"
    }
    steps {
      new {
        id = "deploy"
        run = """
          echo "Deploying to ${{ inputs.environment }}"
          echo "url=https://app.example.com" >> "$GITHUB_OUTPUT"
          """
      }
    }
  }
}
```

--------------------------------

### Define GitHub Actions Workflow with Job Dependencies and Outputs in Pkl

Source: https://context7.com/stefma/pkl-gha/llms.txt

This Pkl code defines a GitHub Actions workflow named 'Build and Deploy' that showcases job dependencies and output passing. It has three jobs: 'build', 'test', and 'deploy'. The 'test' job depends on 'build', and the 'deploy' job depends on both 'build' and 'test'. Outputs from 'build' (version, artifact-id) are passed to subsequent jobs using the 'Context.needs' object.

```pkl
amends "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Workflow.pkl"
import "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Context.pkl"

name = "Build and Deploy"

on {
  push {
    branches {
      "main"
    }
  }
}

jobs {
  ["build"] {
    `runs-on` = "ubuntu-latest"
    outputs {
      ["version"] = "${{ steps.version.outputs.version }}"
      ["artifact-id"] = "${{ steps.upload.outputs.artifact-id }}"
      ["build-status"] = "success"
    }
    steps {
      new {
        id = "version"
        run = """
          VERSION=$(cat version.txt)
          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
          """
      }
      new {
        id = "upload"
        run = """
          echo "artifact-id=12345" >> "$GITHUB_OUTPUT"
          """
      }
    }
  }
  ["test"] {
    `runs-on` = "ubuntu-latest"
    needs = "build"
    `if` = "(Context.needs.result("build")) == 'success'"
    steps {
      new {
        name = "Run tests"
        run = """
          echo "Testing version: (Context.needs.output("build", "version"))"
          echo "Artifact ID: (Context.needs.output("build", "artifact-id"))"
          """
      }
    }
  }
  ["deploy"] {
    `runs-on` = "ubuntu-latest"
    needs {
      "build"
      "test"
    }
    `if` = "(Context.needs.result("build")) == 'success' && (Context.needs.result("test")) == 'success'"
    environment {
      name = "production"
      url = "https://app.example.com"
    }
    steps {
      new {
        name = "Deploy"
        run = """
          echo "Deploying version (Context.needs.output("build", "version"))"
          """
      }
    }
  }
}
```

--------------------------------

### Create Git Tag for Release

Source: https://github.com/stefma/pkl-gha/blob/main/README.md

Creates a git tag following the 'com.github.action@[SEMVER_VERSION]' format. The SEMVER_VERSION must match project version files. This tag is crucial for triggering GitHub releases.

```bash
git tag com.github.action@[SEMVER_VERSION]
```

--------------------------------

### Configure GitHub Actions Permissions and Environments with Pkl

Source: https://context7.com/stefma/pkl-gha/llms.txt

Defines GitHub Actions workflows with specific permissions and deployment environments using the Pkl configuration language. It sets up triggers, required permissions for the workflow, and defines multiple jobs with varying access levels and deployment targets.

```pkl
amends "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Workflow.pkl"
import "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Context.pkl"

name = "Secure Deployment"

on {
  push {
    branches { "main" }
  }
}

permissions {
  contents = "read"
  deployments = "write"
  `id-token` = "write"
  issues = "write"
  `pull-requests` = "write"
  packages = "write"
  pages = "write"
  attestations = "write"
}

jobs {
  ["build"] {
    `runs-on` = "ubuntu-latest"
    permissions {
      contents = "read"
      packages = "write"
    }
    steps {
      new {
        name = "Build"
        run = "npm run build"
      }
    }
  }
  ["deploy-staging"] {
    `runs-on` = "ubuntu-latest"
    needs = "build"
    permissions = "write-all"
    environment {
      name = "staging"
      url = "https://staging.example.com"
    }
    steps {
      new {
        name = "Deploy to staging"
        run = "kubectl apply -f k8s/staging/"
      }
    }
  }
  ["deploy-production"] {
    `runs-on` = "ubuntu-latest"
    needs = "deploy-staging"
    `if` = "(Context.github.custom("ref == 'refs/heads/main'"))"
    environment = "production"
    steps {
      new {
        name = "Deploy to production"
        run = "kubectl apply -f k8s/production/"
      }
    }
  }
}
```

--------------------------------

### Git Branch and Pull Commands

Source: https://github.com/stefma/pkl-gha/blob/main/README.md

Ensures the local 'main' branch is up-to-date with the remote repository before proceeding with release steps. No specific inputs or outputs beyond updating the local branch.

```bash
git checkout main
git pull origin main
```

--------------------------------

### Define GitHub Workflow with Pkl

Source: https://github.com/stefma/pkl-gha/blob/main/README.md

This Pkl code defines a GitHub Action workflow, specifying triggers, jobs, and steps. It demonstrates how to import necessary Pkl modules and utilize Pkl syntax for defining workflow elements like `on`, `jobs`, and `steps`, including fetching secrets.

```pkl
amends "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@[LATEST_VERSION]#/Workflow.pkl"
import "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@[LATEST_VERSION]#/Context.pkl" // Optional
import "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@[LATEST_VERSION]#/Action.pkl" // Optional

name = "Test"

on {
  // Define your `on` triggers. E.g.:
  push {
    branches {
      "main"
    }
  }
  pull_request {}
}

jobs {
  // Define your `jobs`. E.g.: 
  ["test"] {
    `runs-on` = new UbuntuLatest {} // Could also be a string like "ubuntu-latest"
    // Define your `steps`. E.g.:
    steps {
      (Action.checkout) {
        fetchDepth = 0
      }
      new {
        name = "Setup nexus credentials"
        run = """
          mkdir ~/.gradle
          echo "systemProp.nexusUsername=\(Context.secret("NEXUS_USERNAME")) >> ~/.gradle/gradle.properties
          echo "systemProp.nexusPassword=\(Context.secret("NEXUS_PASSWORD")) >> ~/.gradle/gradle.properties
        """
      }
      new {
        name = "Test android app"
        run = "./gradlew testDebugUnitTest"
      }
    }
  }
}
```

--------------------------------

### Convert Pkl to YAML for GitHub Actions

Source: https://github.com/stefma/pkl-gha/blob/main/README.md

These bash commands demonstrate how to convert Pkl workflow files into YAML format, which is usable by GitHub Actions. It shows a command for converting a single file and an alternative for converting multiple files in a directory.

```bash
pkl eval path/to/your/pkl/file.pkl -o path/to/your/pkl/file.yaml
```

```bash
pkl eval path/to/your/pkl/files/*.pkl -o path/to/your/pkl/files/%{moduleName}.yml
```

--------------------------------

### Commit and Push Version Bump

Source: https://github.com/stefma/pkl-gha/blob/main/README.md

Commits the changes made to version files and pushes them to the 'main' branch. This step ensures the project's version is updated after a release.

```bash
git commit -m "Bump version to [SEMVER_VERSION]" .
git push origin main
```

--------------------------------

### Access GitHub Actions Context with Pkl

Source: https://context7.com/stefma/pkl-gha/llms.txt

Demonstrates how to access GitHub Actions context information (e.g., repository name, branch, run ID, secrets, step outputs, environment variables) in a type-safe manner using Pkl and the pkl-gha library.

```pkl
amends "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Workflow.pkl"
import "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Context.pkl"

name = "Context Demo"

on {
  push {}
}

env {
  ["REPO_NAME"] = Context.github.repository
  ["BRANCH_NAME"] = Context.github.refName
  ["RUN_ID"] = Context.github.runId
  ["ACTOR"] = Context.github.actor
}

jobs {
  ["demo"] {
    `runs-on` = "ubuntu-latest"
    steps {
      new {
        name = "Use secrets"
        run = """
          echo "Token: (Context.secrets("GITHUB_TOKEN"))"
          echo "Custom: (Context.secrets("CUSTOM_SECRET"))"
          """
      }
      new {
        id = "build"
        name = "Build step"
        run = """
          echo "result=success" >> "$GITHUB_OUTPUT"
          """
      }
      new {
        name = "Use step output"
        run = "echo Previous result: (Context.steps.outputs("build", "result"))"
      }
      new {
        name = "Use environment"
        run = """
          echo "OS: (Context.runner.os)"
          echo "Workspace: (Context.runner.workspace)"
          echo "ENV VAR: (Context.env("REPO_NAME"))"
          """
      }
    }
  }
}

```

--------------------------------

### Define GitHub Actions Workflow with Pkl

Source: https://context7.com/stefma/pkl-gha/llms.txt

Defines a complete GitHub Actions workflow including triggers, jobs, permissions, and steps using the Pkl configuration language. It leverages the pkl-gha library for type-safe workflow definition.

```pkl
amends "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Workflow.pkl"
import "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Context.pkl"
import "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Action.pkl"

name = "CI Build"

on {
  push {
    branches {
      "main"
      "develop"
    }
    paths {
      "src/**"
      "tests/**"
    }
  }
  pull_request {
    types {
      "opened"
      "synchronize"
      "reopened"
    }
  }
}

permissions {
  contents = "read"
  issues = "write"
  `pull-requests` = "write"
}

concurrency {
  group = "ci-${{ github.ref }}"
  `cancel-in-progress` = true
}

jobs {
  ["build"] {
    `runs-on` = new UbuntuLatest {}
    `timeout-minutes` = 30
    env {
      ["NODE_ENV"] = "production"
      ["CACHE_VERSION"] = 1
    }
    steps {
      (Action.checkout) {
        fetchDepth = 0
      }
      (Action.setupNode) {
        nodeVersion = "18"
        cache = "npm"
      }
      new {
        name = "Install dependencies"
        run = "npm ci"
      }
      new {
        name = "Run tests"
        run = "npm test"
      }
      new {
        name = "Build"
        run = "npm run build"
      }
    }
  }
}

```

--------------------------------

### Push Git Tag to Remote

Source: https://github.com/stefma/pkl-gha/blob/main/README.md

Pushes the newly created git tag to the remote repository. This action is what typically triggers automated release workflows on platforms like GitHub.

```bash
git push origin com.github.action@[SEMVER_VERSION]
```

--------------------------------

### Call Reusable GitHub Actions Workflow with Pkl

Source: https://context7.com/stefma/pkl-gha/llms.txt

This Pkl code demonstrates how to call reusable GitHub Actions workflows. It shows calling a remote workflow 'deploy.yml' with specific inputs and secrets, and also a local workflow './.github/workflows/local-deploy.yml' inheriting secrets. It utilizes the 'ReusableJob' construct and accesses secrets via the 'Context' object.

```pkl
// Calling a reusable workflow
amends "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Workflow.pkl"
import "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/com.github.action@0.0.5#/Context.pkl"

name = "Production Deploy"

on {
  push {
    branches {
      "main"
    }
  }
}

jobs {
  ["call-deploy"] = new ReusableJob {
    uses = "octo-org/workflows/.github/workflows/deploy.yml@v1"
    with {
      ["environment"] = "production"
      ["version"] = "1.2.3"
      ["dry-run"] = false
    }
    secrets {
      ["deploy-token"] = Context.secrets("PROD_DEPLOY_TOKEN")
      ["api-key"] = Context.secrets("API_KEY")
    }
  }
  ["local-workflow"] = new ReusableJob {
    uses = "./.github/workflows/local-deploy.yml"
    secrets = "inherit"
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.