Skip to content
Write Github actions in Go
Go Dockerfile
Use this GitHub Action with your project

Add this Action to an existing workflow or create a new one.

View on Marketplace
Branch: master
Clone or download

Latest commit

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Remove goaction.Getenv API May 8, 2020
actionutil Add githubapi docs May 22, 2020
cmd/goaction Remove goaction.Getenv API May 8, 2020
internal Add githubapi docs May 22, 2020
log Distinguish between info and debug logs May 2, 2020
Dockerfile Update action files Apr 30, 2020
LICENSE Create LICENSE Apr 28, 2020
README.md
action.yml Update action files May 8, 2020
event.go Use autogen May 10, 2020
event_test.go Use autogen May 10, 2020
go.mod Add github api May 22, 2020
go.sum Add github api May 22, 2020
goaction.go Add another example May 23, 2020
goaction_test.go Add output and set-env May 1, 2020

README.md

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

You can’t perform that action at this time.