ghworkflow

README

go-ghworkflow

go-ghworkflow is a Go library that gives a high level interface for working with GitHub Actions workflows. Currently the feature set includes a series of things for invoking GitHub Actions workflows using the workflow_dispatch event, using a pipeline driven style similar to bitfield/script.

Right now, it mostly works only in the context of something run in a GitHub workflow, because:

• It sources the token used for authentication from the environment variable GITHUB_TOKEN
• It determines the repository where the called workflow lives using the environment variable GITHUB_REPOSITORY.

  Note: As of version 0.3.0, you can now specify a different repository in which to create the workflow dispatch event using the WithRepo functional option.

These things should be made more flexible as time allows to make the library more useful. PRs welcome!

Usage

IMPORTANT: For this module to work, your GitHub workflow must meet the following criteria:

• It must accept an input with the name caller_run_id with a type of string.
• It must create a job whose name contains the value of that input.

This is necessary because of how the GitHub API does not return an identifier for the workflow run triggered by a workflow_dispatch event, so we have to derive it by some arbitrary relationship.

WARNING: Before you can start a workflow with a workflow_dispatch event, a version of that workflow must exist on the default repository branch. Otherwise, the GitHub API returns a 404 not found status as if the workflow does not exist. This limitation is noted in the GitHub docs here.

Here's a simple way to use the library to call a workflow, wait for its results, and see if it succeeded or not.

import (
  "log"

  "github.com/yardbirdsax/go-ghworkflow"
)

func main {
  err := ghworkflow.Run("workflow.yaml").Wait().Error
  if err != nil {
    log.Fatal(err)
  }
}

Here's how to pass inputs to the workflow.

import (
  "log"

  "github.com/yardbirdsax/go-ghworkflow"
)

func main {
  inputs := map[string]interface{}{
    "something": "some value",
  }
  err := ghworkflow.Run("workflow.yaml", WithInputs(inputs)).Wait().Error
  if err != nil {
    log.Fatal(err)
  }
}

By default, the module will run the workflow on the same ref that it is executed from using conditional logic as follows:

• If the module is used in a workflow that is executing from a PR, it will use the source branch of the pull request.
• If the module is used in a workflow that is triggered from a push event, it will use the same branch on which the commit occurred.

You can override this using the WithGitRef optional function. Please note: There is currently no way to specify a specific commit SHA; you can only specify a ref, which means there's some chance that the workflow being executed will come from a different commit than the one triggering the event. (This is a very race-like condition and you probably don't have to worry about it unless you've got a very high rate of merges / commits to your workflow files.)

err := ghworkflow.Run(
  "workflow.yaml",
  WithInputs(inputs),
  WithGitRef("main")
).Wait().Error

Documentation

Index

• Constants
• func WithDeadline(deadline time.Time) workflowOptsFn
• func WithGitRef(ref string) workflowOptsFn
• func WithInputs(inputs map[string]interface{}) workflowOptsFn
• func WithLoggingChannel(logChan chan (logMessage)) workflowOptsFn
• func WithMaxRetryPeriod(period time.Duration) workflowOptsFn
• func WithRepo(owner string, repo string) workflowOptsFn
• type LogChannel
• type WorkflowRun
  • func NewWorkflowRun(path string, optsFn ...workflowOptsFn) *WorkflowRun
  • func Run(path string, optsFn ...workflowOptsFn) *WorkflowRun
  • func (r *WorkflowRun) Run() *WorkflowRun
  • func (r *WorkflowRun) Wait() *WorkflowRun

Constants

const (
	Error logLevel = iota
	Warning
	Info
	Debug
	Trace
)

Functions

func WithDeadline

func WithDeadline(deadline time.Time) workflowOptsFn

WithDeadline sets the deadline for the workflow run to start and complete.

func WithGitRef

func WithGitRef(ref string) workflowOptsFn

WithGitRef sets the Git ref used when creating the dispatch event. This is the ref that the Actions platform will use for sourcing the workflow code.

func WithInputs

func WithInputs(inputs map[string]interface{}) workflowOptsFn

WithInputs sets the inputs for the workflow dispatch.

func WithLoggingChannel

func WithLoggingChannel(logChan chan (logMessage)) workflowOptsFn

WithLoggingChannel allows you to pass in a Go channel that will receive events from long running operations. Events are sent asynchronously and will not block execution.

func WithMaxRetryPeriod

func WithMaxRetryPeriod(period time.Duration) workflowOptsFn

WithMaxRetryPeriod sets the maximum time to wait for the workflow run to start and complete.

func WithRepo

func WithRepo(owner string, repo string) workflowOptsFn

WithRepo lets you specify a different repository where the workflow should be invoked. You must always specify the repository name; if the owner name is a blank string, the current value will not be replaced.

Types

type LogChannel

type LogChannel chan (logMessage)

LogChannel is a channel that can be used to receive messages during long operations, such as waiting for a workflow to complete. It is used with the WithLogChannel functional option.

type WorkflowRun

type WorkflowRun struct {

	// Reference to the workflow definition
	Workflow *github.Workflow
	// Reference to the workflow run
	WorkflowRun *github.WorkflowRun
	// An identifier that is used to tie the workflow dispatch event to the workflow run.
	CallerRunID string
	// The error that caused the workflow to either fail to start or fail during execution.
	Error error
	// contains filtered or unexported fields
}

WorkflowRun is a struct representing a single run of a workflow.

func NewWorkflowRun

func NewWorkflowRun(path string, optsFn ...workflowOptsFn) *WorkflowRun

func Run

func Run(path string, optsFn ...workflowOptsFn) *WorkflowRun

Run executes a workflow by path and returns a WorkflowRun struct for the current execution. To use this properly, the workflow _must_ accept an input called 'caller_run_id', and have a job that will use that input in its name.

func (*WorkflowRun) Run

func (r *WorkflowRun) Run() *WorkflowRun

Run executes a workflow with the configured properties, then finds the linked workflow run by matching the struct's `CallerRunID` property with job names. It then fills in the workflow run details in the struct for later reference.

func (*WorkflowRun) Wait

func (r *WorkflowRun) Wait() *WorkflowRun

Wait pauses execution until the workflow completes, then populates the Error property of the struct if the workflow run failed.