DependabotManagedActions.pkl

//===----------------------------------------------------------------------===//
// Copyright © 2025-2026 Apple Inc. and the Pkl project authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//===----------------------------------------------------------------------===//
/// A template for writing GitHub Actions workflows, whose actions are pinned to specific SHAs, and
/// updated by dependabot.
///
/// Typically, this module is placed in `.github/index.pkl`.
/// To produce output, the `-m` (or `--multiple-file-output-path`) flag must pointed at the repo's
/// `.github` directory.
///
/// In addition to the regular workflows, this template also produces a fake workflow called
/// `__lockfile__.yml`.
/// The contents of this lockfile are used to replace the `uses` of versioned actions with their
/// git SHA.
/// For example, `uses: checkout@v6` becomes `uses: checkout@abc123 # v6`.
/// If the lockfile doesn't already exist, or if a new action is used, action versions are
/// resolved to their SHA and the lockfile is updated as a result of evaluation.
///
/// Additionally, this template produces a `dependabot.yml` file, which configures GitHub to
/// automatically update the workflow YAMLs with updated git shas as new action versions are
/// released.
///
/// ## Example
///
/// Here is an example of this template in use, along with the corresponding `PklProject`.
/// In addition to these two files, the project must be resolved with
/// `pkl project resolve .github/`, which will create `.github/PklProject.deps.json` to also be
/// checked into the repo.
///
/// To render this into YAML, run `pkl eval --project-dir .github .github/index.pkl`.
///
/// ```
/// // .github/index.pkl
/// amends "@pkl.github.dependabotManagedActions/DependabotManagedActions.pkl"
///
/// import "@com.github.actions/catalog.pkl"
///
/// workflows {
///   ["workflows/build.yml"] {
///     jobs {
///       ["do-build"] {
///         catalog.`actions/checkout@v6`
///         catalog.`actions/setup-go@v5`
///         new {
///           run = "go test ./..."
///         }
///       }
///     }
///   }
/// }
/// ```
///
/// ```
/// // .github/PklProject
/// amends "pkl:Project"
///
/// dependencies {
///   ["com.github.actions"] {
///     uri = "package://pkg.pkl-lang.org/pkl-pantry/com.github.actions@1.3.0"
///   }
///   ["pkl.github.dependabotManagedActions"] {
///     uri = "package://pkg.pkl-lang.org/pkl-pantry/pkl.github.dependabotManagedActions@1.0.0"
///   }
/// }
/// ```
module pkl.github.dependabotManagedActions.DependabotManagedActions

import "@com.github.actions/Workflow.pkl"
import "@com.github.dependabot/v2/Dependabot.pkl"

import "internal/LockfileGenerator.pkl"

/// The effective workflows produced by this job, keyed by the workflow filename.
///
/// Example:
///
/// ```
/// workflows {
///   ["workflow/prb.yml"] = myPrbWorkflow
/// }
/// ```
workflows: Mapping<String, Workflow>

/// Dependabot configuration.
///
/// The `github-actions` ecosystem will be automatically added to this.
dependabot: Dependabot

local generator: LockfileGenerator = new {
  workflows = module.workflows.toMap().values
}

local locks = generator.locks

local effectiveDependabot = (dependabot) {
  updates {
    new {
      `package-ecosystem` = "github-actions"
      directory = "/"
      schedule {
        interval = "weekly"
      }
      ignore {
        new {
          `dependency-name` = "*"
          `update-types` {
            "version-update:semver-major"
          }
        }
      }
    }
  }
}

local convertedWorkflows: Mapping<String, Workflow> = (workflows) {
  [[true]] {
    output {
      renderer {
        converters {
          ["jobs[*].steps[*].uses"] = (it) -> locks.getOrNull(it)?.renderDirective ?? it
        }
      }
    }
  }
}

output {
  text = throw("This module only supports multiple-file output. Evaluate me with the `-m` flag.")
  files = new {
    [generator.lockfileName] = generator.lockfileWorkflow.output
    ["dependabot.yml"] = effectiveDependabot.output
    for (name, workflow in convertedWorkflows) {
      [name] = workflow.output
    }
  }
}