Packages > pkg.pkl-lang.org/pkl-pantry/com.github.actions

com.github.actions.Workflow1.3.0

Overview
Properties
Methods
Classes
Type Aliases

module com.github.actions.Workflow

A Pkl template for writing GitHub Action workflows.

Module URI:: package://pkg.pkl-lang.org/pkl-pantry/com.github.actions@1.3.0#/Workflow.pkl
Source code:: Workflow.pkl
Known subtypes in package:
Known usages in package:
All versions:

This module provides a set of definitions for GitHub Action workflows, including triggers, jobs, steps, and environment variables.

Using context

There is a helper for referencing context values directly off of the this module.

When amending Workflow, the context can be referenced using module.context.

Example:

amends "@com.github.actions/Workflow.pkl"

jobs {
  ["build"] {
    `runs-on` = "ubuntu-latest"
    steps {
      new {
        run =
          """
          echo "My ref is \(module.context.github.ref)"
          """
      }
    }
  }
}

Using typed steps

Pkl provides helpers to steps which call into externally defined actions in a typesafe way. For example, it provides code assistance for calling the actions/checkout action while providing completions and typechecking for each input.

These steps are defined as classes (or modules) that extend module AbstractTypedStep.

Using the catalog

This package includes a catalog of typed steps, within the actions/ subpath. Additionally, the catalog.pkl module is an index module of all catalogs.

To use a catalog item, simply import catalog.pkl when defining a workspace. For example:

amends "@com.github.actions/Workflow.pkl"

import "@com.github.actions/catalog.pkl"

jobs {
  ["build"] {
    `runs-on` = "ubuntu-latest"
    steps {
      // use the checkout action without any further parameterization
      catalog.`actions/checkout@v6`

      // use the cache/restore action with some extra parameters
      (catalog.`actions/cache/restore@v4`) {
        with {
          key = "my-cache-key"
          pathList { "foo"; "bar" }
        }
      }
    }
  }
}

Generating more action types

It is possible to generate more action types, using the generate-action script from the com.github.actions.contrib package.

These actions turn into their own modules, and should be checked into source code. For further instructions, see its documentation.

Properties(show inherited)

link

hidden

output: ModuleOutput (pkl.base)Source

The output of this module.

Defaults to all module properties rendered as either Pcf or the format specified on the command line.
link

name: String?Source

The name of the workflow.

GitHub displays the names of your workflows under your repository's "Actions" tab. If you omit name, GitHub displays the workflow file path relative to the root of the repository.
link

`run-name`: String?Source

The name for workflow runs generated from the workflow.

GitHub displays the workflow run name in the list of workflow runs on your repository's "Actions" tab. If run-name is omitted or is only whitespace, then the run name is set to event-specific information for the workflow run. For example, for a workflow triggered by a push or pull_request event, it is set as the commit message or the title of the pull request.

This value can include expressions and can reference the github and inputs contexts.
link

on: On|TriggerEventName|Listing<TriggerEventName>Source

Define which events can cause the workflow to run.

For a list of available events, see Events that trigger workflows.
link

env: EnvironmentVariables?Source

A map of variables that are available to the steps of all jobs in the workflow.

You can also set variables that are only available to the steps of a single job or to a single step. For more information, see DefaultJob.env and Step.env. When more than one environment variable is defined with the same name, GitHub uses the most specific variable. For example, an environment variable defined in a step will override job and workflow environment variables with the same name, while the step executes. An environment variable defined for a job will override a workflow variable with the same name, while the job executes.
link

concurrency: Concurrency?Source

Use concurrency to ensure that only a single job or workflow using the same concurrency group will run at a time.

A concurrency group can be any string or expression. The expression can only use github, inputs and vars contexts. For more information about expressions, see Evaluate expressions in workflows and actions. You can also specify concurrency at the job level. For more information, see BaseJob.concurrency. This means that there can be at most one running and one pending job in a concurrency group at any time. When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be pending. Any existing pending job or workflow in the same concurrency group, if it exists, will be canceled and the new queued job or workflow will take its place. To also cancel any currently running job or workflow in the same concurrency group, specify cancel-in-progress: true. To conditionally cancel currently running jobs or workflows in the same concurrency group, you can specify cancel-in-progress as an expression with any of the allowed expression contexts.
link

permissions: (Permissions|"read-all"|"write-all")?Source

You can use permissions to modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access.

For more information, see Use GITHUB_TOKEN for authentication in workflows. You can use permissions either as a top-level key, to apply to all jobs in the workflow, or within specific jobs. When you add the permissions key within a specific job, all actions and run commands within that job that use the GITHUB_TOKEN gain the access rights you specify. For more information, see BaseJob.permissions. Owners of an organization can restrict write access for the GITHUB_TOKEN at the repository level. For more information, see Disabling or limiting GitHub Actions for your organization. When a workflow is triggered by the pull_request_target event, the GITHUB_TOKEN is granted read/write repository permission, even when it is triggered from a public fork. For more information, see Events that trigger workflows.
link

jobs: Jobs Source

A workflow run is made up of one or more jobs, which run in parallel by default.

To run jobs sequentially, you can define dependencies on other jobs using the needs keyword. Each job runs in a runner environment specified by runs-on. You can run an unlimited number of jobs as long as you are within the workflow usage limits. For more information, see Billing and usage for GitHub-hosted runners and Actions limits for self-hosted runner usage limits. If you need to find the unique identifier of a job running in a workflow run, you can use the GitHub API.

For more information, see REST API endpoints for GitHub Actions.
link

hidden

context: context Source

The contextual values available within a GitHub Action.

Methods(show inherited)

link

function

getClass(): Class (pkl.base)Source

Returns the class of this.
link

function

toString(): String (pkl.base)Source

Returns a string representation of this.

This method is used to convert the values of string interpolation expressions to strings.
link

function

ifNonNull<Result>(transform: (NonNull) -> Result): Result? (pkl.base)Source

Returns this |> transform if this is non-null, and null otherwise.

This method is the complement of the ?? operator and the equivalent of an Option type's map and flatMap methods.
link

function

hasProperty(name: String): Boolean (pkl.base)Source

Tells if this object has a property with the given name.
link

function

getProperty(name: String): unknown (pkl.base)Source

Returns the value of the property with the given name.

Throws if a property with this name does not exist.
link

function

getPropertyOrNull(name: String): unknown? (pkl.base)Source

Returns the value of the property with the given name.

Returns null if a property with this name does not exist.
link

function

toDynamic(): Dynamic (pkl.base)Source

Converts this object to a Dynamic object.
link

function

toMap(): Map<String, unknown> (pkl.base)Source

Converts this object to a Map.
link

function
relativePathTo(other: Module): List<String> (pkl.base)Source

Returns the relative, descendent directory path between this module and other.
Throws if no such path exists.

For example, if module mod1 has path /dir1/mod1.pkl, and module mod2 has path /dir1/dir2/dir3/mod2.pkl, then mod1.relativePathTo(mod2) will return List("dir2", "dir3").

A common use case is to compute the directory path between a template located at the root of a hierarchy (say rootModule.pkl) and the currently evaluated module (accessible via the module keyword):
```
import "rootModule.pkl" // self-import
path = rootModule.relativePathTo(module)
```

Classes

link

abstract class

Trigger Source
link

class

BaseTrigger extends Trigger Source

The base trigger, with no event types associated
link

class

BranchProtectionRule extends Trigger Source
link

class

CheckRun extends Trigger Source
link

class

CheckSuite extends Trigger Source
link

class

Discussion extends Trigger Source
link

class

DiscussionComment extends Trigger Source
link

class

IssueComment extends Trigger Source
link

class

Issues extends Trigger Source
link

class

Label extends Trigger Source
link

class

MergeGroup extends Trigger Source
link

class

Milestone extends Trigger Source
link

class

Project extends Trigger Source
link

class

ProjectCard extends Trigger Source
link

class

ProjectColumn extends Trigger Source
link

class

PullRequest extends Trigger Source
link

class

PullRequestReview extends Trigger Source
link

class

PullRequestReviewComment extends Trigger Source
link

class

Push extends Trigger Source
link

class

RegistryPackage extends Trigger Source
link

class

Release extends Trigger Source
link

class

RepositoryDispatch extends Trigger Source
link

class

Schedule Source
link

class

WorkflowCall extends Trigger Source

Allows workflows to be reused by other workflows.
link

class

WorkflowCallOutput Source
link

class

WorkflowCallSecrets Source
link

class

WorkflowDispatch extends Trigger Source
link

class

WorkflowInput Source
link

class

WorkflowRun extends Trigger Source
link

class

On Source
link

class

Permissions Source
link

class

Concurrency Source

Type Aliases

link

typealias

Jobs = Mapping<String(matches(Regex("[a-zA-Z_][a-zA-Z0-9_-]*"))), Job>(!isEmpty, hasValidJobReferences)Source
link

typealias

Job = Job|AbstractTypedJob Source

A job within a workflow run.
link

typealias

Step = Step Source

A step within a job.
link

typealias

TriggerEventName = "branch_protection_rule"|"check_run"|"check_suite"|"create"|"delete"|"deployment"|"deployment_status"|"discussion"|"discussion_comment"|"fork"|"gollum"|"issue_comment"|"issues"|"label"|"merge_group"|"milestone"|"page_build"|"project"|"project_card"|"project_column"|"public"|"pull_request"|"pull_request_review"|"pull_request_review_comment"|"pull_request_target"|"push"|"registry_package"|"release"|"repository_dispatch"|"schedule"|"status"|"watch"|"workflow_call"|"workflow_dispatch"|"workflow_run"Source

The name of an event that triggers a workflow.
link

typealias

BranchProtectionRuleType = "created"|"edited"|"deleted"Source
link

typealias

CheckRunType = "created"|"rerequested"|"completed"|"requested_action"Source
link

typealias

CheckSuiteType = "completed"|"requested"|"rerequested"Source
link

typealias

DiscussionType = "created"|"edited"|"deleted"|"transferred"|"pinned"|"unpinned"|"labeled"|"unlabeled"|"locked"|"unlocked"|"category_changed"|"answered"|"unanswered"Source
link

typealias

DiscussionCommentType = "created"|"edited"|"deleted"Source
link

typealias

IssueCommentType = "created"|"edited"|"deleted"Source
link

typealias

IssuesType = "opened"|"edited"|"deleted"|"transferred"|"pinned"|"unpinned"|"closed"|"reopened"|"assigned"|"unassigned"|"labeled"|"unlabeled"|"locked"|"unlocked"|"milestoned"|"demilestoned"Source
link

typealias

LabelType = "created"|"edited"|"deleted"Source
link

typealias

MergeGroupType = "checked_requested"Source
link

typealias

MilestoneType = "created"|"closed"|"opened"|"edited"|"deleted"Source
link

typealias

ProjectType = "created"|"updated"|"closed"|"reopened"|"edited"|"deleted"Source
link

typealias

ProjectCardType = "created"|"moved"|"converted"|"edited"|"deleted"Source
link

typealias

ProjectColumnType = "created"|"updated"|"moved"|"deleted"Source
link

typealias

PullRequestType = "assigned"|"unassigned"|"review_requested"|"review_request_removed"|"labeled"|"unlabeled"|"opened"|"edited"|"closed"|"reopened"|"synchronize"|"ready_for_review"|"locked"|"unlocked"|"converted_to_draft"|"demilestoned"|"milestoned"|"auto_merge_enabled"|"auto_merge_disabled"Source
link

typealias

PullRequestReviewType = "submitted"|"edited"|"dismissed"Source
link

typealias

PullRequestReviewCommentType = "created"|"edited"|"deleted"Source
link

typealias

PullRequestTargetType = "assigned"|"unassigned"|"labeled"|"unlabeled"|"opened"|"edited"|"closed"|"reopened"|"synchronize"|"converted_to_draft"|"ready_for_review"|"locked"|"unlocked"|"review_requested"|"review_request_removed"|"auto_merge_enabled"|"auto_merge_disabled"Source
link

typealias

RegistryPackageType = "published"|"updated"Source
link

typealias

ReleaseType = "published"|"unpublished"|"created"|"edited"|"deleted"|"prereleased"|"released"Source
link

typealias

WorkflowInputType = "boolean"|"string"|"choice"|"environment"|"number"Source
link

typealias

WorkflowRunType = "requested"|"completed"|"in_progress"Source
link

typealias

EnvironmentVariables = Mapping<String, (String|Boolean|Number)>Source
link

typealias

Permission = "read"|"write"|"none"Source