Write a GitHub Action in Pkl 🚀

[StefMa]

Update to my original post below 👇

The GitHub Action template is available at
👉 https://github.com/StefMa/pkl-gha/
and ready to use in version 0.0.1

Simply amend the template

amends "package://pkg.pkl-lang.org/github.com/stefma/pkl-gha/[email protected]#/GitHubAction.pkl"

and fill out the require properties name, on and jobs.
Running the following command will produce your Action workflow in yaml format:

pkl eval YourFirstAction.pkl

More examples can be found there
👉 https://github.com/StefMa/pkl-gha/tree/d266b8b2f9a541774b2f648a1c583d057c931462/examples

If you miss something don't hesitate to create an issue, hit me up here or create a PR to add it ❤️

Original post:

Hello together,

I have been playing around a bit with Pkl the last few days and thought I create a GitHub Action package as an example.
Similar to the already available com.circleci package.

The following shows how a Workflow in Pkl can be look like:

amends "package://pkl-pkg.vercel.app/[email protected]/[email protected]#/Workflow.pkl"

import "package://pkl-pkg.vercel.app/[email protected]/[email protected]#/GitHubAction.pkl"

name = "PrintHelloWorld"

// Fake: not implemented yet in generic GitHubAction module...
local class LabelTrigger extends GitHubAction.Trigger {
    name = "label"
    types = new Listing<String> {
        "created"
    }
}

onRaw {
    [Push] = new GitHubAction.Push {
        branches {
            "develop"
        }
    }
    ["workflow_dispatch"] = new GitHubAction.WorkflowDispatch {}
}

onListing {
    new GitHubAction.Push {
        branches {
            "main"
        }
    }
    new GitHubAction.WorkflowDispatch {}
    new LabelTrigger {}
}

jobs {
    ["print"] = new {
        `runs-on` = GitHubAction.UbuntuLatest
        steps {
            new GitHubAction.RunStep {
                name = "Hello World"
                run = "echo Hello World"
            }
            new GitHubAction.Step {
                name = "date"
            }
            new GitHubAction.RunStep {
                name = "Print date"
            run = "date"
            }
            new GitHubAction.UsesStep {
                name = "Checkout"
                uses = "actions/checkout@v4"
                with = new {
                    ["ref"] = "develop"
                }
            }
            new GitHubAction.UsesStep {
                name = "Checkout"
                uses = "actions/checkout@v4"
                with = new {
                    ["ref"] = "develop"
                }
            }
            new GitHubAction.UsesStep {
                name = "Slack"
                id = "Slack"
                `if` = "${{ failure() }}"
                uses = "slackapi/[email protected]"
                with = new {
                    ["payload"] = """
                    {
                        "blocks": [
                            {
                                "type": "section",
                                "text": {
                                    "type": "mrkdwn",
                                    "text": ":alert: Develop is broken!"
                                }
                            }
                        ]
                    }
                    """
                }
            }
        }
    }
}

The (yml) output of this can be found here

name: PrintHelloWorld
'on':
  push:
    branches:
    - main
  workflow_dispatch: {}
  label:
    types:
    - created
jobs:
  print:
    runs-on:
      name: ubuntu-latest
    steps:
    - name: Hello World
      run: echo Hello World
    - name: date
    - name: Print date
      run: date
    - name: Checkout
      uses: actions/checkout@v4
      with:
        ref: develop
    - name: Checkout
      uses: actions/checkout@v4
      with:
        ref: develop
    - name: Slack
      id: Slack
      if: ${{ failure() }}
      uses: slackapi/[email protected]
      with:
        payload: "{\n\t\"blocks\": [\n\t\t{\n\t\t\t\"type\": \"section\",\n\t\t\t\"text\": {\n\t\t\t\t\"type\": \"mrkdwn\",\n\t\t\t\t\"text\": \":alert: Develop is broken!\"\n\t\t\t}\n\t\t}\n\t]\n}"

The source code can be found here
👉 [email protected]
(Because I'm not sure if this is good enough to be published on my GitHub Account I didn't do so yet 😁 )

What do you think? 🙃

Its obviously not ready for production and early early alpha.
I might even change the package module in the future 🙃
I just did this for testing Pkl.

My questions are:

• Is this how Pkl should look like? Do I something wrong? Can someting be improved? Do I hold it wrong? 🤔
• Is it correct that I amend the Workflow.pkl file in my "consumer"? (I did this because of the templating description (docs))
• It it correct that I import the GitHubAction.pkl file in my "consumer? (I did this because I wanna distrinight between the template and the "building blocks" of a Workflow)
• Can I improve the on statement somehow? I introduced onRaw and onListing because I think onListing looks way better than the onRaw with the mapping and you know the names of each "on" trigger. I wanted to hide this. However, using onListing instead of just on looks also not soo good. So my question is: Can I somehow define on as a List, but map it to a Mapping for the output later? If so, how?
• ... Nothing more yet 😁

[bioball]

Hey, awesome!

Is it correct that I amend the Workflow.pkl file in my "consumer"? (I did this because of the templating description (docs))

Yup!

It it correct that I import the GitHubAction.pkl file in my "consumer? (I did this because I wanna distrinight between the template and the "building blocks" of a Workflow)

You can certainly do this. It means that your consumers then need to re-import GitHubAction when they use your template, though.

Can I improve the on statement somehow? I introduced onRaw and onListing because I think onListing looks way better than the onRaw with the mapping and you know the names of each "on" trigger. I wanted to hide this. However, using onListing instead of just on looks also not soo good. So my question is: Can I somehow define on as a List, but map it to a Mapping for the output later? If so, how?

I'd actually recommend defining on as a class, because it has a few known keys. Something like this:

on: On

class On {
  schedule: Listing<ScheduleTrigger>
  push: PushOrPullTrigger
  pull_request: PushOrPullTrigger
  pull_request_target: PushOrPullTrigger
}

class PushOrPullTrigger {
  paths: Listing<String>
  `paths-ignore`: Listing<String>
}

class ScheduleTrigger {
  cron: String
}

Some other comments:

• Your package URI should include your version only once. To do this, you can use pkg.pkl-lang.org as your package URI for GItHub releases. For example, package://pkg.pkl-lang.org/github.com/<user>/<repo>/[email protected].
• You should define the output renderer in your template, so because GitHub Actions only accepts YAML:

  output {
    renderer = new YamlRenderer {}
  }
  

• It's a really good idea to add doc comments to these properties so your users know what they mean.
• You can try using the json schema generator to generate your base template, because there's already an existing JSON Schema.

[StefMa]

Thank you for the feedback @bioball.

You can certainly do this. It means that your consumers then need to re-import GitHubAction when they use your template, though.

Does this mean I could also move all classes into the Workflow directly?
And then just amend a single file?
I guess I also have to import that (same) file?

Doesn't it look a bit strange to amend and import the same file? 🤔

Your package URI should include your version only once. To do this, you can use pkg.pkl-lang.org as your package URI for GItHub releases. For example, package://pkg.pkl-lang.org/github.com///[email protected].

Does this mean that package://pkg.pkl-lang.org/github.com/ will always redirect to GitHub release?
Are there are options to publish the package and using the "official" pkg.pkl-lang.org/ domain?

You should define the output renderer in your template, so because GitHub Actions only accepts YAML:

What is the affect of this? I don't have to specifcy my output anymore and it will always be rendered as Yaml?
What happen if users want to try another output, e.g. json? Would it fail?

Thank you again 🙃

[bioball]

Does this mean I could also move all classes into the Workflow directly?
And then just amend a single file?
I guess I also have to import that (same) file?

Doesn't it look a bit strange to amend and import the same file?

You shouldn't need to import the same file if you are already amending it.

Does this mean that package://pkg.pkl-lang.org/github.com/ will always redirect to GitHub release?
Are there are options to publish the package and using the "official" pkg.pkl-lang.org/ domain?

Yeah, all it does is redirect! You can try it out locally:

$ curl --head https://pkg.pkl-lang.org/github.com/foo/bar/[email protected]
HTTP/2 301
server: AppleHttpServer/00f954eb1bdc0aaa7c04e434a9aff1da4f8c1183
date: Thu, 29 Feb 2024 15:42:44 GMT
content-type: text/html
content-length: 169
location: https://github.com/foo/bar/releases/download/[email protected]/[email protected]
x-b3-traceid: cd702eac5e962f3d
strict-transport-security: max-age=31536000

What is the affect of this? I don't have to specifcy my output anymore and it will always be rendered as Yaml?
What happen if users want to try another output, e.g. json? Would it fail?

This means that you do not need to use the -f flag anymore, you can just pkl eval file.pkl and it will produce YAML. In fact, this means that the -f flag has no effect on the output format anymore.

This is appropriate for GitHub Actions, though, because it can only be in YAML.

Underneath the hood, the -f flag sets the pkl.outputFormat property, and this determines which renderer to use in base.pkl: https://github.com/apple/pkl/blob/main/stdlib/base.pkl#L95-L105

[StefMa]

You shouldn't need to import the same file if you are already amending it.

I remember why I did it 🙃
When I have everything in the same file, pkl will not fail in case some mandatory property is not overriden!
As an example, I use your On class and define with on: On.
If the consumer don't override it, it just prints 'on': {}.
But actually it is mandatory to override so pkl should fail here...
When I have two different files it will work correctly.

Also just for reference:
The json-schema ist this one: https://json.schemastore.org/github-workflow.json
The one you posted is for creating an action 🙃
And running with

./pkl eval package://pkg.pkl-lang.org/pkl-pantry/[email protected]#/generate.pkl -m . -p source="https://json.schemastore.org/github-workflow.json"

fails with errors:

–– Pkl Error ––
A stack overflow occurred.

548 | typeArguments {
      ^^^^^^^^^^^^^^^
at org.json_schema.contrib.internal.TypesGenerator#generateObjectType.typeArguments (https://github.com/apple/pkl-pantry/blob/[email protected]/packages/org.json_schema.contrib/internal/TypesGenerator.pkl#L548-554)

48 | if (typeArguments.isEmpty) ""
         ^^^^^^^^^^^^^
at pkl.experimental.syntax.TypeNode#DeclaredTypeNode.renderTypeArguments (https://github.com/apple/pkl-pantry/blob/[email protected]/packages/pkl.experimental.syntax/TypeNode.pkl#L48-48)

┌─ 3812 repetitions of:
│ 
│ 49 | else "<" + typeArguments.toList().map((t) -> t.render(currentIndent)).join(", ") + ">"
│                                                   ^^^^^^^^^^^^^^^^^^^^^^^
│ at pkl.experimental.syntax.TypeNode#DeclaredTypeNode.renderTypeArguments.<function#1> (https://github.com/apple/pkl-pantry/blob/[email protected]/packages/pkl.experimental.syntax/TypeNode.pkl#L49-49)
│ 
│ 49 | else "<" + typeArguments.toList().map((t) -> t.render(currentIndent)).join(", ") + ">"
│                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
│ at pkl.experimental.syntax.TypeNode#DeclaredTypeNode.renderTypeArguments (https://github.com/apple/pkl-pantry/blob/[email protected]/packages/pkl.experimental.syntax/TypeNode.pkl#L49-49)
│ 
│ 51 | function render(currentIndent: String) = name.render(currentIndent) + renderTypeArguments(currentIndent)
│                                                                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
│ at pkl.experimental.syntax.TypeNode#DeclaredTypeNode.render (https://github.com/apple/pkl-pantry/blob/[email protected]/packages/pkl.experimental.syntax/TypeNode.pkl#L51-51)
│ 
│ 72 | let (childrenRendered = members.toList().map((t) -> t.render(currentIndent)))
│                                                          ^^^^^^^^^^^^^^^^^^^^^^^
│ at pkl.experimental.syntax.TypeNode#UnionTypeNode.render.<function#3> (https://github.com/apple/pkl-pantry/blob/[email protected]/packages/pkl.experimental.syntax/TypeNode.pkl#L72-72)
│ 
│ 72 | let (childrenRendered = members.toList().map((t) -> t.render(currentIndent)))
│                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
│ at pkl.experimental.syntax.TypeNode#UnionTypeNode.render (https://github.com/apple/pkl-pantry/blob/[email protected]/packages/pkl.experimental.syntax/TypeNode.pkl#L72-72)
└─

40 | type.render(currentIndent)
     ^^^^^^^^^^^^^^^^^^^^^^^^^^
at pkl.experimental.syntax.TypeAliasNode#renderAlias[#4] (https://github.com/apple/pkl-pantry/blob/[email protected]/packages/pkl.experimental.syntax/TypeAliasNode.pkl#L40-40)

35 | local function renderAlias(currentIndent: String) = new Listing {
                                                         ^^^^^^^^^^^^^
at pkl.experimental.syntax.TypeAliasNode#renderAlias (https://github.com/apple/pkl-pantry/blob/[email protected]/packages/pkl.experimental.syntax/TypeAliasNode.pkl#L35-41)

46 | currentIndent + renderAlias(currentIndent)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^
at pkl.experimental.syntax.TypeAliasNode#render (https://github.com/apple/pkl-pantry/blob/[email protected]/packages/pkl.experimental.syntax/TypeAliasNode.pkl#L46-46)

122 | typealiases?.toList()?.map((t) -> t.render(currentIndent))?.join("\n\n")
                                        ^^^^^^^^^^^^^^^^^^^^^^^
at pkl.experimental.syntax.ModuleNode#render.<function#2> (https://github.com/apple/pkl-pantry/blob/[email protected]/packages/pkl.experimental.syntax/ModuleNode.pkl#L122-122)

122 | typealiases?.toList()?.map((t) -> t.render(currentIndent))?.join("\n\n")
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
at pkl.experimental.syntax.ModuleNode#render (https://github.com/apple/pkl-pantry/blob/[email protected]/packages/pkl.experimental.syntax/ModuleNode.pkl#L122-122)

36 | text = render("")
            ^^^^^^^^^^
at pkl.experimental.syntax.Node#output.text (https://github.com/apple/pkl-pantry/blob/[email protected]/packages/pkl.experimental.syntax/Node.pkl#L36-36)

[jasongwartz]

@StefMa A nice trick for when you want to require something to be overridden is to set it to an error message:

on: On = throw("`on` must be overridden") // or a more descriptive message :P

when run, errors and shows:

–– Pkl Error ––
`on` must be overridden

1 | on: On = throw("`on` must be overridden")
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
at test#on (file:///Users/jasongwartz/git/pkl-community/pkl-typescript/test.pkl, line 1)

106 | text = renderer.renderDocument(value)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
at pkl.base#Module.output.text (https://github.com/apple/pkl/blob/0.25.1/stdlib/base.pkl#L106)

But then when someone amends your module, if they set on = new On { ... }, it evaluates without error.

[StefMa]

@jasongwartz after reading this I think it is more an error than expected behavior... 🤔
I do some more testing and might create an issue.

However thanks for the workaround 👍 🙂

Update

I created an issue for that 🙃
👉 #284

[jamesward]

This is cool and maybe we can work together! I'd also started working on Pkl for GitHub Actions before I came across this discussion.
Module:
https://github.com/jamesward/pklgha

Usage in my Effect Oriented Programming book:
https://github.com/EffectOrientedProgramming/book/blob/main/.github/workflows/test.pkl

Usage to release pklgha:
https://github.com/jamesward/pklgha/blob/main/.github/workflows/release.pkl

Still a lot to do but it has been fun to have actual reuseability and abstractions. :)

[StefMa]

Wow! Cool stuff you have in there @jamesward. Nice work 👏

I also just published my current version here
👉 https://github.com/StefMa/pkl-gha/

I have some more things already available 🤓

maybe we can work together

Sure, would love to!
Feel free to conribute to my repository 😁

I also have some feedback regarding your implementation:

• I'm not a fan of using Gradle for "this simple" template. Its brings just unnecessary complexity. The pkl CLI is all you need.
• I struggle a bit with the idea to provide "build in"/"ready to use" workflows. For example the GitHubActionScala. It is really cool that you "can just use this" and no additional set up is mandatory. However, doing this brings other questions. How do youn deal with updates of actions? What if someone whats to customize this "a bit" more? Should he than 100% switch to their own implementation? On the other side, why not providing a simple entry point for the scala action (to customize it) plus a few steps afterwards? Might be worth to brainstorm a bit more about this... 💭

[jamesward]

Sweet! Thanks for getting that stuff up there.

Some decisions about what goes where depends on if this should / can ultimately end up in https://github.com/apple/pkl-pantry
Maybe @holzensp or someone else from the Pkl team can let us know about that possibility. I also saw someone trying to automate creating GitHub schemas: apple/pkl-pantry#23

I think we will need Gradle to generate the PklDoc.

Yeah, the Scala one shows the cool power of Pkl to create abstractions and likely should be somewhere else with a dependency on the base GitHubAction project. Definitely need to brainstorm more about the design and escape hatches that make sense.

Kinda related I've been wondering what the best approach is to automating the GHA yamls generation. In an ideal world, GitHub would support server-side git commit hooks but since that seems unlikely, I wonder what alternatives could enable some form of automated eval - client-side hook? A GitHub App that'd automate things? I wonder if others have thought more about this.