goaction

package module
v0.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 21, 2020 License: Apache-2.0 Imports: 7 Imported by: 7

README

goaction

GoDoc

Package goaction enables writing Github Actions in Go.

The idea is: write a standard Go script, one that works with go run, and use it as Github action. The script's inputs - flags and environment variables, are set though the Github action API. This project will generate all the required files for the script (This generation can be done automattically with Github action integration). The library also exposes neat API to get workflow information.

Required Steps

  • Write a Go script.

  • Add goaction configuration in .github/workflows/goaction.yml.

  • Push the project to Github.

See simplest example for a Goaction script: posener/goaction-example, or an example that demonstrait using Github APIs: posener/goaction-issues-example.

Writing a Goaction Script

Write Github Action by writing Go code! Just start a Go module with a main package, and execute it as a Github action using Goaction, or from the command line using go run.

A go executable can get inputs from the command line flag and from environment variables. Github actions should have a action.yml file that defines this API. Goaction bridges the gap by parsing the Go code and creating this file automatically for you.

The main package inputs should be defined with the standard flag package for command line arguments, or by os.Getenv for environment variables. These inputs define the API of the program and goaction automatically detect them and creates the action.yml file from them.

Additionally, goaction also provides a library that exposes all Github action environment in an easy-to-use API. See the documentation for more information.

Code segments which should run only in Github action (called "CI mode"), and not when the main package runs as a command line tool, should be protected by a if goaction.CI { ... } block.

Goaction Configuration

In order to convert the repository to a Github action, goaction command line should run on the "main file" (described above). This command can run manually (by ./cmd/goaction) but luckily goaction also comes as a Github action :-)

Goaction Github action keeps the Github action file updated according to the main Go file automatically. When a PR is made, goaction will post a review explaining what changes to expect. When a new commit is pushed, Goaction makes sure that the Github action files are updated if needed.

Add the following content to .github/workflows/goaction.yml

on:
  pull_request:
    branches: [master]
  push:
    branches: [master]
jobs:
  goaction:
    runs-on: ubuntu-latest
    steps:
    - name: Check out repository
      uses: actions/checkout@v2
    - name: Update action files
      uses: posener/goaction@v1
      with:
        # Optional: required only for commenting on PRs.
        github-token: '${{ secrets.GITHUB_TOKEN }}'
    # Optional: now that the script is a Github action, it is possible to run it in the
    # workflow.
    - name: Example
      uses: [./](./)

Goaction Artifacts

./action.yml: A "metadata" file for Github actions. If this file exists, the repository is considered as Github action, and the file contains information that instructs how to invoke this action. See metadata syntax. for more info.

./Dockerfile: A file that contains instructions how to build a container, that is used for Github actions. Github action uses this file in order to create a container image to the action. The container can also be built and tested manually:

$ docker build -t my-action .
$ docker run --rm my-action

Annotations

Goaction parses Go script file and looks for annotations that extends the information that exists in the function calls. Goaction annotations are a comments that start with //goaction: (no space after slashes). They can only be set on a var definition. The following annotations are available:

  • //goaction:required - sets an input definition to be "required".

  • //goaction:skip - skips an input out output definition.

  • //goaction:description <description> - add description for os.Getenv.

  • //goaction:default <value> - add default value for os.Getenv.

Using Goaction

A list of projects which are using Goaction (please send a PR if your project uses goaction and does not appear her).

Sub Packages

  • actionutil: Package actionutil provides utility functions for Github actions.

  • log: Package log is an alternative package for standard library "log" package for logging in Github action environment.

Readme created from Go doc with goreadme

Documentation

Overview

Package goaction enables writing Github Actions in Go.

The idea is: write a standard Go script, one that works with `go run`, and use it as Github action. The script's inputs - flags and environment variables, are set though the Github action API. This project will generate all the required files for the script (This generation can be done automattically with Github action integration). The library also exposes neat API to get workflow information.

Required Steps

- [x] Write a Go script.

- [x] Add `goaction` configuration in `.github/workflows/goaction.yml`.

- [x] Push the project to Github.

See simplest example for a Goaction script: (posener/goaction-example) https://github.com/posener/goaction-example, or an example that demonstrait using Github APIs: (posener/goaction-issues-example) https://github.com/posener/goaction-issues-example.

Writing a Goaction Script

Write Github Action by writing Go code! Just start a Go module with a main package, and execute it as a Github action using Goaction, or from the command line using `go run`.

A go executable can get inputs from the command line flag and from environment variables. Github actions should have a `action.yml` file that defines this API. Goaction bridges the gap by parsing the Go code and creating this file automatically for you.

The main package inputs should be defined with the standard `flag` package for command line arguments, or by `os.Getenv` for environment variables. These inputs define the API of the program and `goaction` automatically detect them and creates the `action.yml` file from them.

Additionally, goaction also provides a library that exposes all Github action environment in an easy-to-use API. See the documentation for more information.

Code segments which should run only in Github action (called "CI mode"), and not when the main package runs as a command line tool, should be protected by a `if goaction.CI { ... }` block.

Goaction Configuration

In order to convert the repository to a Github action, goaction command line should run on the **"main file"** (described above). This command can run manually (by ./cmd/goaction) but luckily `goaction` also comes as a Github action :-)

Goaction Github action keeps the Github action file updated according to the main Go file automatically. When a PR is made, goaction will post a review explaining what changes to expect. When a new commit is pushed, Goaction makes sure that the Github action files are updated if needed.

Add the following content to `.github/workflows/goaction.yml` 

on:
  pull_request:
    branches: [master]
  push:
    branches: [master]
jobs:
  goaction:
    runs-on: ubuntu-latest
    steps:
    - name: Check out repository
      uses: actions/checkout@v2
    - name: Update action files
      uses: posener/goaction@v1
      with:
        # Optional: required only for commenting on PRs.
        github-token: '${{ secrets.GITHUB_TOKEN }}'
    # Optional: now that the script is a Github action, it is possible to run it in the
    # workflow.
    - name: Example
      uses: ./

Goaction Artifacts

./action.yml: A "metadata" file for Github actions. If this file exists, the repository is considered as Github action, and the file contains information that instructs how to invoke this action. See (metadata syntax) https://help.github.com/en/actions/building-actions/metadata-syntax-for-github-actions. for more info.

./Dockerfile: A file that contains instructions how to build a container, that is used for Github actions. Github action uses this file in order to create a container image to the action. The container can also be built and tested manually: 

$ docker build -t my-action .
$ docker run --rm my-action

Annotations

Goaction parses Go script file and looks for annotations that extends the information that exists in the function calls. Goaction annotations are a comments that start with `//goaction:` (no space after slashes). They can only be set on a `var` definition. The following annotations are available:

* `//goaction:required` - sets an input definition to be "required".

* `//goaction:skip` - skips an input out output definition.

* `//goaction:description <description>` - add description for `os.Getenv`.

* `//goaction:default <value>` - add default value for `os.Getenv`.

Using Goaction

A list of projects which are using Goaction (please send a PR if your project uses goaction and does not appear her).

* (posener/goreadme) http://github.com/posener/goreadme

Index

Constants

This section is empty.

Variables

View Source 
var (
	// CI is set to true when running under github action
	//
	// This variable can be used to protect code segments which should only run in Github action
	// mode and not in command line mode:
	//
	//  if goaction.CI {
	// 		// Code that should run only in Github action mode.
	// 	}
	CI = os.Getenv("CI") == "true"
	// The path to the GitHub home directory used to store user data. For example, /github/home.
	Home = os.Getenv("HOME")
	// The name of the workflow
	Workflow = os.Getenv("GITHUB_WORKFLOW")
	// 	A unique number for each run within a repository. This number does not change if you re-run
	// the workflow run.
	RunID = os.Getenv("GITHUB_RUN_ID")
	// 	A unique number for each run of a particular workflow in a repository. This number begins at
	// 1 for the workflow's first run, and increments with each new run. This number does not change
	// if you re-run the workflow run.
	RunNum = os.Getenv("GITHUB_RUN_NUMBER")
	// The unique identifier (id) of the action.
	ActionID = os.Getenv("GITHUB_ACTION")
	// The name of the person or app that initiated the workflow. For example, octocat.
	Actor = os.Getenv("GITHUB_ACTOR")
	// The owner and repository name. For example, octocat/Hello-World.
	Repository = os.Getenv("GITHUB_REPOSITORY")
	// The name of the webhook event that triggered the workflow.
	Event = EventType(os.Getenv("GITHUB_EVENT_NAME"))
	// 	The GitHub workspace directory path. The workspace directory contains a subdirectory with a
	// copy of your repository if your workflow uses the actions/checkout action. If you don't use
	// the actions/checkout action, the directory will be empty. For example,
	// /home/runner/work/my-repo-name/my-repo-name.
	Workspace = os.Getenv("GITHUB_WORKSPACE")
	// The commit SHA that triggered the workflow. For example,
	// ffac537e6cbbf934b08745a378932722df287a53.
	SHA = os.Getenv("GITHUB_SHA")
	// The branch or tag ref that triggered the workflow. For example, refs/heads/feature-branch-1.
	// If neither a branch or tag is available for the event type, the variable will not exist.
	Ref = os.Getenv("GITHUB_REF")
	//	Only set for forked repositories. The branch of the head repository.
	ForkedHeadRef = os.Getenv("GITHUB_HEAD_REF")
	// Only set for forked repositories. The branch of the base repository.
	ForkedBaseRef = os.Getenv("GITHUB_BASE_REF")
)

Github actions default environment variables. See https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables#default-environment-variables

Functions

func AddPath added in v0.0.7 

func AddPath(path string)

AddPath prepends a directory to the system PATH variable for all subsequent actions in the current job. The currently running action cannot access the new path variable. See https://help.github.com/en/actions/reference/workflow-commands-for-github-actions#adding-a-system-path.

func Branch 

func Branch() string

Branch returns the push branch for push flow or empty string for other flows.

func Export added in v0.0.7 

func Export(name string, value string) error

Export sets an environment variable that will also be visible for all following Github actions in the current workflow.

func GetCheckRun added in v0.0.5 

func GetCheckRun() (*github.CheckRunEvent, error)

GetCheckRun returns information about a current check run.

func GetCheckSuite added in v0.0.5 

func GetCheckSuite() (*github.CheckSuiteEvent, error)

GetCheckSuite returns information about a current check suite.

func GetCreate added in v0.0.5 

func GetCreate() (*github.CreateEvent, error)

GetCreate returns information about a current create.

func GetDelete added in v0.0.5 

func GetDelete() (*github.DeleteEvent, error)

GetDelete returns information about a current delete.

func GetDeployment added in v0.0.5 

func GetDeployment() (*github.DeploymentEvent, error)

GetDeployment returns information about a current deployment.

func GetFork added in v0.0.5 

func GetFork() (*github.ForkEvent, error)

GetFork returns information about a current fork.

func GetGollum added in v0.0.5 

func GetGollum() (*github.GollumEvent, error)

GetGollum returns information about a current gollum.

func GetIssueComment added in v0.0.5 

func GetIssueComment() (*github.IssueCommentEvent, error)

GetIssueComment returns information about a current issue comment.

func GetIssues added in v0.0.5 

func GetIssues() (*github.IssuesEvent, error)

GetIssues returns information about a current issues.

func GetLabel added in v0.0.5 

func GetLabel() (*github.LabelEvent, error)

GetLabel returns information about a current label.

func GetMilestone added in v0.0.5 

func GetMilestone() (*github.MilestoneEvent, error)

GetMilestone returns information about a current milestone.

func GetPageBuild added in v0.0.5 

func GetPageBuild() (*github.PageBuildEvent, error)

GetPageBuild returns information about a current page build.

func GetProject added in v0.0.5 

func GetProject() (*github.ProjectEvent, error)

GetProject returns information about a current project.

func GetProjectCard added in v0.0.5 

func GetProjectCard() (*github.ProjectCardEvent, error)

GetProjectCard returns information about a current project card.

func GetPublic added in v0.0.5 

func GetPublic() (*github.PublicEvent, error)

GetPublic returns information about a current public.

func GetPullRequest added in v0.0.5 

func GetPullRequest() (*github.PullRequestEvent, error)

GetPullRequest returns information about a current pull request.

func GetPullRequestReview added in v0.0.5 

func GetPullRequestReview() (*github.PullRequestReviewEvent, error)

GetPullRequestReview returns information about a current pull request review.

func GetPullRequestReviewComment added in v0.0.5 

func GetPullRequestReviewComment() (*github.PullRequestReviewCommentEvent, error)

GetPullRequestReviewComment returns information about a current pull request review comment.

func GetPush added in v0.0.5 

func GetPush() (*github.PushEvent, error)

GetPush returns information about a current push.

func GetRelease added in v0.0.5 

func GetRelease() (*github.ReleaseEvent, error)

GetRelease returns information about a current release.

func GetRepositoryDispatch added in v0.0.5 

func GetRepositoryDispatch() (*github.RepositoryDispatchEvent, error)

GetRepositoryDispatch returns information about a current repository dispatch.

func GetStatus added in v0.0.5 

func GetStatus() (*github.StatusEvent, error)

GetStatus returns information about a current status.

func GetWatch added in v0.0.5 

func GetWatch() (*github.WatchEvent, error)

GetWatch returns information about a current watch.

func IsForked 

func IsForked() bool

IsForked return true if the action is running on a forked repository.

func Output added in v0.0.7 

func Output(name string, value string, desc string)

Output sets Github action output. See https://help.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-output-parameter.

func Owner 

func Owner() string

Owner returns the name of the owner of the Github repository.

func PrNum 

func PrNum() int

PrNum returns pull request number for PR flow or -1 in other flows.

func Project 

func Project() string

Project returns the name of the project of the Github repository.

func Setenv added in v0.0.7 

func Setenv(name string, value string)

Setenv sets an environment variable that will only be visible for all following Github actions in the current workflow, but not in the current action. See https://help.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-environment-variable.

Types

type EventType 

type EventType string

A Github action triggering event. See https://help.github.com/en/actions/reference/events-that-trigger-workflows. 

const (
	EventCheckRun                 EventType = "check_run"
	EventCheckSuite               EventType = "check_suite"
	EventCreate                   EventType = "create"
	EventDelete                   EventType = "delete"
	EventDeployment               EventType = "deployment"
	EventFork                     EventType = "fork"
	EventGollum                   EventType = "gollum"
	EventIssueComment             EventType = "issue_comment"
	EventIssues                   EventType = "issues"
	EventLabel                    EventType = "label"
	EventMilestone                EventType = "milestone"
	EventPageBuild                EventType = "page_build"
	EventProject                  EventType = "project"
	EventProjectCard              EventType = "project_card"
	EventPublic                   EventType = "public"
	EventPullRequest              EventType = "pull_request"
	EventPullRequestReview        EventType = "pull_request_review"
	EventPullRequestReviewComment EventType = "pull_request_review_comment"
	EventPush                     EventType = "push"
	EventRegistryPackage          EventType = "registry_package"
	EventRelease                  EventType = "release"
	EventStatus                   EventType = "status"
	EventWatch                    EventType = "watch"
	EventSchedule                 EventType = "schedule"
	EventRepositoryDispatch       EventType = "repository_dispatch"
)

All Github action event types.

Source Files

View all Source files

Directories

Path Synopsis
Package actionutil provides utility functions for Github actions.
 Package actionutil provides utility functions for Github actions.
cmd
goaction
Creates action files for Go code
 Creates action files for Go code
internal
comments
genapi
Generates actionutil/githubapi.go
 Generates actionutil/githubapi.go
genevents
Generates events.go and events_test.go files.
 Generates events.go and events_test.go files.
metadata
Package metadata loads main go file to a datastructure that describes Github action metadata.
 Package metadata loads main go file to a datastructure that describes Github action metadata.
Package log is an alternative package for standard library "log" package for logging in Github action environment.
 Package log is an alternative package for standard library "log" package for logging in Github action environment.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.