GitHub Actions

Managing CI/CD configuration by clicking through the GitHub UI gets old fast. Secrets drift, environments diverge between repos, and nobody remembers which workflow sets which variable. The GitHub Actions plugin lets formae manage GitHub Actions secrets, variables, environments, branch policies, workflow files, OIDC claims, runner groups, and org-level permissions as code.

Repository: formae-plugin-gha

Installation

git clone https://github.com/platform-engineering-labs/formae-plugin-gha.git
cd formae-plugin-gha
make install

This builds the plugin and installs it to ~/.pel/formae/plugins/gha/. The formae agent discovers installed plugins automatically on startup. Requires Go 1.26+.

Configuration

Target

Configure a GitHub target in your Forma file:

import "@formae/formae.pkl"
import "@gha/gha.pkl"

target: formae.Target = new formae.Target {
    label = "github"
    namespace = "GHA"
    config = new gha.Config {
        owner = "my-org"
        // repo = "my-repo"  // optional, required for repo-scoped resources
    }
}

owner is required. repo is optional at the target level, but repo-scoped resources need it set somewhere (target or resource).

Most teams pull owner and repo from environment variables so the same forma can point at different repos:

config = new gha.Config {
    owner = read("env:GHA_OWNER")
    repo = read("env:GHA_REPO")
}

Authentication

The plugin resolves a GitHub token automatically. No secrets in your Forma files, no agent restart when tokens rotate. Resolution order:

  1. GITHUB_TOKEN environment variable
  2. gh auth token CLI command
  3. ~/.config/gh/hosts.yml config file

If you already have the gh CLI authenticated, there is nothing else to do. Otherwise:

export GITHUB_TOKEN=$(gh auth token)

Required scopes

Scope Required for
repo All repository resources
workflow Files under .github/workflows/
admin:org Organization-scoped resources

Examples

Clone the repo and resolve Pkl dependencies before running:

git clone https://github.com/platform-engineering-labs/formae-plugin-gha.git
cd formae-plugin-gha
pkl project resolve examples/ci-pipeline

Available examples:

Example Description
ci-pipeline Apply and destroy workflows, staging and production environments, AWS OIDC secrets, branch policies, all in one forma
infra-to-app GHA plus Azure plugin working together to provision PostgreSQL, deploy an app, and verify it end-to-end

The examples read GHA_OWNER and GHA_REPO from the environment, so point them at a scratch repo first:

export GHA_OWNER=my-org
export GHA_REPO=my-scratch-repo

Then evaluate and apply:

# Evaluate an example
formae eval examples/ci-pipeline/main.pkl

# Apply resources
formae apply examples/ci-pipeline/main.pkl

Typed workflow files

Workflow files are written as typed Pkl using the com.github.actions package from pkl-pantry, rendered to YAML, and committed as GHA::Repo::File resources. The same forma creates the workflows and the config they depend on. One apply, whole pipeline.

Supported Resources

Resources come in three scopes. Pick the scope that matches where the setting lives in the GitHub UI:

  • Repo resources live on a single repository. Set repo in the target or on the resource.
  • Environment resources belong to a deployment environment inside a repo.
  • Org resources operate at the organization level and need admin:org.

Repo

Type Description
GHA::Repo::Variable Repository Actions variable
GHA::Repo::Secret Repository Actions secret, sealed-box encrypted
GHA::Repo::Environment Deployment environment with protection rules
GHA::Repo::File Repository file via the Contents API
GHA::Repo::Workflow Structured workflow file, typed via com.github.actions
GHA::Repo::OIDCClaims Repository OIDC subject claim customization

Environment

Type Description
GHA::Environment::Variable Environment-scoped variable
GHA::Environment::Secret Environment-scoped secret
GHA::Environment::BranchPolicy Deployment branch policy

Org

Type Description
GHA::Org::Variable Organization Actions variable
GHA::Org::Secret Organization Actions secret
GHA::Org::RunnerGroup Organization self-hosted runner group
GHA::Org::OIDCClaims Organization OIDC subject claim customization
GHA::Org::Permissions Organization Actions permissions
GHA::Org::DefaultWorkflowPermissions Organization default workflow token permissions

What's next

  • Learn how targets work in Target
  • See Res for wiring outputs between resources
  • Browse the plugin SDK to build your own

Release notes

See release notes for changes per version.