Forgejo Actions | Using Actions

Actions are reusable pieces of code that you can use in your CI workflows.

Using Actions

For example, to check out the contents of the repository you can use the actions/checkout action. To use it, add the following step to a job in your workflow:

- name: Check out the repository
  uses: https://data.forgejo.org/actions/checkout@v4

This specifies that this step uses the action https://data.forgejo.org/actions/checkout, version v4.

You can also specify an action like uses: actions/checkout@v4. In this case the runner will prefix it with the DEFAULT_ACTIONS_URL and proceed like normal. The DEFAULT_ACTIONS_URL is https://data.forgejo.org/ by default, but it can be changed by the instance administrator. For this reason it is strongly recommended to use fully qualified URLs. In this guide we will use the shorter notation for brevity.

You can also load an action from a local directory instead of a remote repository. This is called a local action.

Action inputs

An Action can have parameters, called inputs. You can usually read which inputs an action has in its README. To specify the inputs for an action, you can use the with key like so:

- name: Check out the repository
  uses: actions/checkout@v4
  with:
    ref: my-feature-branch
    path: some/subdirectory
    show-progress: true

Action dependencies

Since Actions are simply scripts run in your CI workflow, they usually have dependencies. For example, the actions/checkout action depends on NodeJS. If it is not present the action will fail. When using non-standard container images it is important to check that the required dependencies are present. If they are not you can try these fixes:

Find a container image that does have the dependencies pre-installed.
Install the dependencies during the workflow, by using a package manager.
Find an alternative action that doesn’t have the dependencies.

Local actions

If an action’s uses statement starts with ./ it will be loaded from the specified local directory, instead of being cloned from a remote repository. The layout and content of the actions directory will be exactly the same as with a remote action.

Take a look at the example.

The action is taken from a local directory, from the perspective of the runner. This means you will typically need to have a checkout action before being able to use a local action.

Creating your own actions

It is fairly simple to create your own actions. An action is really just a directory with an action.yml in it. There are three types of actions, node, docker and composite.

These types of actions are both explained further below.

Tip: When first developing an action, it is useful to load it as a local action for testing.

`action.yml`

The action.yml file contains all the metadata for the action. It decides the name, description, inputs, outputs and how to run the action.

Take a look at this simple example:

name: 'Example Action'
author: 'Me, I wrote it'
description: |
  A simple action that just takes some input and writes it to a file.

inputs:
  message:
    description: 'The message to be stored'
    default: 'default message'

outputs:
  time:
    description: 'The time when the action was run'

runs: ...

The content of the runs key determines what type of action it is.

`node` actions

Node actions are executed using NodeJS. NodeJS will not automatically be installed, so if it is not present in the container image the action will fail.

Node actions have the following information in the runs key:

runs:
  using: 'node20'
  main: 'index.js'

The main key determines the entry point for execution.

For more information about writing node actions, check the GitHub documentation. Keep in mind that certain details differ between GitHub and Forgejo.

`docker` actions

Docker actions are executed using a container engine. They can only be used on runners that provide one, like Docker or Podman.

Docker actions have the following information in the runs key:

runs:
  using: 'docker'
  image: 'Containerfile'
  args:
    - ${{ inputs.message }} # This also needs to be defined in the inputs section above.

The image key points at the Containerfile that should be used to build the image that will be run. The Containerfile contains the configuration for the base image, as well as an entrypoint. Arguments can be passed with the args key.

For more information about writing Docker actions, check the GitHub documentation. Keep in mind that certain details differ between GitHub and Forgejo.

`composite` actions

Composite actions are simply a series of steps from a normal workflow, packaged as an action for easier reuse.

Composite actions have the following information in the runs key:

runs:
  using: 'composite'
  steps:
    - name: Print message
      run: echo "$MESSAGE"
      shell: bash
      env:
        MESSAGE: ${{ inputs.message }} # This also needs to be defined in the inputs section above.

    - name: Some other step
      ...

Composite actions can use other actions just like normal workflows. You can also write scripts, commit them to the action repository, and then use them in the action by calling them with a run key.