Creating Go Actions

Gitea's CI system, Gitea Actions, was recently released in version 1.19.0. Gitea Actions is an internal CI/CD system, offering near compatibility with GitHub Actions. One key difference is that Gitea supports both Go and JavaScript actions, while GitHub only supports JavaScript actions natively (though you can use any programming language for Docker container actions).

Go actions provide a way for gophers who are not familiar with JavaScript to create native actions. However, compared to JavaScript actions, Go actions may be slower because they need to be built as executables before running. But you don't need to put the generated javascript files into dist in a Go action.

In this guide, we'll show you how to create a Go action in Gitea. Before diving in, you should have a basic understanding of Gitea Actions. If you're not familiar with it, we recommend reading Hacking on Gitea Actions.

A Simple Go Action​

First, let's create a simple Go action. You'll need to create a repository called simple-go-action on your Gitea instance and clone it:

git clone <repo-url>
cd simple-go-action
# create the go.mod file
go mod init simple-go-action

The metadata file is essential for actions, and its filename must be either action.yml or action.yaml. Here's an example action.yml file:

name: 'Simple Go Action'
description: 'A simple Gitea action written in go'
runs:
  using: 'go'
  main: 'main.go'

To read more about the metadata syntax, you can see the Metadata syntax for GitHub Actions.

You may notice that we use using: 'go' in the metadata, specifying Go as the runtime for this action. Since GitHub doesn't support Go actions natively, you won't find this in GitHub's documentation.

Next, add the main.go file with a simple logic to print a "Hello world" string:

package main

import "fmt"

func main() {
	fmt.Println("Hello world")
}

Now the action is ready to be tested. Commit and push the code to Gitea. To test the action, create another repository called test-simple-go-action and add a workflow file using the following code. Please replace <action-url> with the URL of your action. The <action-url> should be like http(s)://<your-gitea-instance-url>/<owner>/<repo>@<version>, for example: https://gitea.com/Zettat123/simple-go-action@v1. The <version> could be a tag, a branch or a commit SHA. For more information, see using-release-management-for-actions.

name: 'Test Go Action'
on: [push]
jobs:
  use-go-action:
    runs-on: ubuntu-latest
    steps:
      - name: Setup Go
        uses: actions/setup-go@v3
        with:
          go-version: '1.20'

      - name: Use Go Action  
        uses: <action-url>

Since the action is written in Go and the runs-on environment may not have Go installed, you'll need to set up a Go runtime before using the action. The setup-go action works well in this case, but we'll discuss cases where it doesn't later. After pushing the workflow file, you can see the result in the Actions tab.

Inputs and Outputs​

You can specify the data that the action will use through inputs parameters and the data that the action can provide to other actions through outputs parameters. For more information, see GitHub's documentation on inputs and outputs

To use inputs and outputs, you'll need to update the action.yml file:

name: 'Simple Go Action'
description: 'A simple Gitea action written in go'
inputs:
  username:
    description: 'The username to print'
    required: true
outputs:
  time:
    description: 'The time when the action was called'
runs:
  using: 'go'
  main: 'main.go'

You'll also need to update the main.go file:

package main

import (
	"fmt"
	"os"
	"time"
)

func main() {
	username := readInputs()
	fmt.Printf("username is %s\n", username)

	err := writeOutputs("time", time.Now().Format("2006-01-02 15:04:05"))
	if err != nil {
		panic(err)
	}
}

func readInputs() string {
	username := os.Getenv("INPUT_USERNAME")
	return username
}

func writeOutputs(k, v string) (err error) {
	msg := fmt.Sprintf("%s=%s", k, v)
	outputFilepath := os.Getenv("GITHUB_OUTPUT")
	f, err := os.OpenFile(outputFilepath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
	if err != nil {
		return
	}
	defer func() {
		if cErr := f.Close(); cErr != nil && err == nil {
			err = cErr
		}
	}()
	if _, err = f.Write([]byte(msg)); err != nil {
		return
	}
	return
}

In the workflow that uses the action, you need to add the code related to inputs and outputs:

name: 'Test Go Action'
on: [push]
jobs:
  use-go-action:
    runs-on: ubuntu-latest
    steps:
      - name: Setup Go
        uses: actions/setup-go@v3
        with:
          go-version: '1.20'

      - name: Use Go Action  
        id: use-go-action
        uses: <action-url>
        with:
          username: foo

      - name: Print Output
        run: echo 'output time is ${{ steps.use-go-action.outputs.time }}'

After pushing the updated workflow file, you will see the result:

Good! You have successfully used inputs and outputs in your action. You may find that the code for reading inputs and writing outputs looks complicated. To simplify the code, you can use the go-githubactions SDK:

package main

import (
	"fmt"
	"time"

	gha "github.com/sethvargo/go-githubactions"
)

func main() {
	username := gha.GetInput("username")
	fmt.Printf("username is %s\n", username)

	gha.SetOutput("time", time.Now().Format("2006-01-02 15:04:05"))
}

If you re-run the workflow, the result will be:

As shown in screenshot, the third-party packages need to be downloaded to build the executable. If you don't want to download third-party packages every time, you can use go mod vendor to create the vendor directory to store packages.

Pre and Post​

In the action.yml file, we set the runs.main to main.go to specify the code that the action will run. In addition to the main, you can also specify the pre and the post for an action. The pre allows you to run some code before running the main and the post allows you to run some code at the end of the job. If you need more information, please read GitHub's documentation on pre and post.

Let's add the pre and the post to the action. Firstly, you need to create a pre directory and add the pre.go file in it:

package main

import "fmt"

func main() {
	fmt.Println("Pre of Simple Go Action")
}

Next, create the post directory and post.go file in the similar way:

package main

import "fmt"

func main() {
	fmt.Println("Post of Simple Go Action")
}

And you'll also need to update the action.yml file:

name: 'Simple Go Action'
description: 'A simple Gitea action written in go'
inputs:
  username:
    description: 'The username to print'
    required: true
outputs:
  time:
    description: 'The time when the action was called'
runs:
  using: 'go'
  main: 'main.go'
  pre: "pre/pre.go"
  post: "post/post.go"

Now the structure of the directory should be like:

├── action.yml
├── go.mod
├── main.go
├── post
│   └── post.go
└── pre
    └── pre.go

Everything looks ok! But when you re-run the workflow, you may see an error: "go": executable file not found in $PATH. The reason is that the code in pre will be executed before calling the setup-go action, and the Go runtime has not yet been set up. In this case, you'll need to use an image with Go installed to run this workflow and you won't need to call the setup-go action since the image already has the Go runtime. You can use container.image to specify the image (replace <image-with-go> with an image with go installed):

name: 'Test Go Action'
on: [push]
jobs:
  use-go-action:
    runs-on: ubuntu-latest
    container:
      image: <image-with-go>
    steps:
      - name: Use Go Action  
        id: use-go-action
        uses: <action-url>
        with:
          username: foo

      - name: Print Output
        run: echo 'output time is ${{ steps.use-go-action.outputs.time }}'

Then the workflow will work. You'll see the output of the pre in Set up job:

and the output of the post in Complete job:

Now you should have a basic understanding of Gitea's Go actions. If you have any ideas or encounter any bugs, please feel free to create issues or pull requests. We can work together to make Gitea Actions even better.

You can find the demo code in the following repositories:

• simple-go-action: https://gitea.com/Zettat123/simple-go-action
• test-simple-go-action: https://gitea.com/Zettat123/test-simple-go-action

And there is also a usable go action to publish release to Gitea https://gitea.com/actions/release-action