/cdkactions

A CDK for GitHub Actions

Primary LanguageTypeScriptApache License 2.0Apache-2.0

cdkactions

Release codecov NPM PyPI

A cdk for GitHub Actions. cdkactions allows you to define GitHub Actions workflows and create abstractions in TypeScript and synthesize those workflows into YAML that the GitHub Actions runner expects.

This project was heavily influenced by cdk8s and cdktf.

Contents

Overview

cdkactions allows you to define GitHub Action Workflows and Jobs as a tree of constructs which are bundled into a Stack construct and exposed through a toplevel App construct. These constructs can then be synthesized into the actual .yaml configuration that GitHub Actions runs.

Additionally cdkactions optionally provides a GitHub Actions workflow that ensures the synthesized .yaml manifests are up to date with the actual cdkactions configuration.

Why

cdkactions was built because composite actions are too restrictive to be of much use. Currently (as of December 2020) composite actions can't call other actions through uses: which prevents them from caching, uploading artifacts, and more. Here's the most relevant issue about composite actions. cdkactions solves these issues by allowing the user to create a fully-featured Stack that can then be published to npm and used within other cdkactions instances.

On top of that, cdkactions provides additional features like strong type-checking as well as significantly better modularity.

At a glance

demo

Validation workflow

cdkactions provides a validation workflow that ensures .yaml manifests are up to date with cdkactions configuration. This workflow can also push updated manifests when it detects any changes by setting the pushUpdatedManifests flag to true. However, if this option is enabled you must create a GitHub Actions secret called CDKACTIONS_TOKEN that contains a Personal Access Token with the workflow scope (This workaround is required because the default GitHub token doesn't have permission to change workflow files).

Library

cdkactions also contains a library of additional constructs:

  • CheckoutJob - A job that inserts a checkout step as the first step to run.
  • CDKActionsStack - A stack that contains the validation workflow described above.

Getting Started

Examples

The CI for this repo is also bootstrapped using cdkactions see the config for a more complicated example.

License

This project is distributed under the Apache License, Version 2.0.