From 1c0f4b4328be002398cd3779d7bc59567e96d782 Mon Sep 17 00:00:00 2001 From: Kwonunn Date: Sat, 12 Apr 2025 13:53:34 +0200 Subject: [PATCH] complete actions guide --- docs/user/actions/actions.md | 67 ++++++++++++++++++++++++-- docs/user/actions/advanced-features.md | 2 +- docs/user/actions/basic-concepts.md | 2 +- docs/user/actions/overview.md | 2 +- docs/user/actions/quick-start.md | 2 +- docs/user/actions/reference.md | 4 +- plan.md | 6 +-- 7 files changed, 71 insertions(+), 14 deletions(-) diff --git a/docs/user/actions/actions.md b/docs/user/actions/actions.md index f1de4ef0..03189a17 100644 --- a/docs/user/actions/actions.md +++ b/docs/user/actions/actions.md @@ -3,7 +3,7 @@ title: Forgejo Actions | Using Actions license: 'CC-BY-SA-4.0' --- -When using Forgejo Actions CI you may find yourself repeatedly wanting to do the same thing in different workflows. For example, many workflows start by checking out the contents of their repository. To avoid repeating yourself, you can use an `Action`. An Action is like a function in a programming language. It is a procedure you can call with some inputs which will perform a specific task. +Actions are reusable pieces of code that you can use in your CI workflows. ## Using Actions @@ -51,7 +51,7 @@ If an action's `uses` statement starts with `./` it will be loaded from the spec ## 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`, `composite` and `docker`. +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. @@ -59,7 +59,7 @@ These types of actions are both explained further below. ### `actions.yml` -The `actions.yml` file contains all the metadata for the action. It decides the name, description, inputs, outputs and steps taken. +The `actions.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: @@ -74,10 +74,67 @@ inputs: 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: + +```yaml +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](https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-javascript-action). 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: + +```yaml +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](https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-docker-container-action). 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: + +```yaml runs: using: 'composite' steps: - - run: echo ${{ inputs.message }} > message.txt + - 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 + ... ``` -You can run any commands with the `run` key that you may also run normally in a workflow. +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. diff --git a/docs/user/actions/advanced-features.md b/docs/user/actions/advanced-features.md index e87f4df1..31035118 100644 --- a/docs/user/actions/advanced-features.md +++ b/docs/user/actions/advanced-features.md @@ -1,5 +1,5 @@ --- -title: Forgejo Actions advanced features +title: Forgejo Actions | Advanced features license: 'CC-BY-SA-4.0' --- diff --git a/docs/user/actions/basic-concepts.md b/docs/user/actions/basic-concepts.md index b7719b8a..1f1223ee 100644 --- a/docs/user/actions/basic-concepts.md +++ b/docs/user/actions/basic-concepts.md @@ -1,5 +1,5 @@ --- -title: 'Forgejo Actions basic concepts' +title: 'Forgejo Actions | Basic concepts' license: 'CC-BY-SA-4.0' --- diff --git a/docs/user/actions/overview.md b/docs/user/actions/overview.md index c0a7ea68..cfed56f1 100644 --- a/docs/user/actions/overview.md +++ b/docs/user/actions/overview.md @@ -1,5 +1,5 @@ --- -title: 'Forgejo Actions user guide' +title: 'Forgejo Actions | User guide' license: 'CC-BY-SA-4.0' --- diff --git a/docs/user/actions/quick-start.md b/docs/user/actions/quick-start.md index 5a023218..5435f37b 100644 --- a/docs/user/actions/quick-start.md +++ b/docs/user/actions/quick-start.md @@ -1,5 +1,5 @@ --- -title: 'Forgejo Actions quick start guide' +title: 'Forgejo Actions | Quick start guide' license: 'CC-BY-SA-4.0' --- diff --git a/docs/user/actions/reference.md b/docs/user/actions/reference.md index ea95c091..71047844 100644 --- a/docs/user/actions/reference.md +++ b/docs/user/actions/reference.md @@ -1,5 +1,5 @@ --- -title: Forgejo Actions Reference +title: Forgejo Actions | Reference license: 'CC-BY-SA-4.0' --- @@ -14,7 +14,7 @@ Jump to the [context reference](#contexts). The syntax and semantics of the YAML file describing a `workflow` are _partially_ explained here. If something is not documented here, the [GitHub Actions documentation](https://docs.github.com/en/actions) may be helpful. However, GitHub Actions and Forgejo Actions _are not the same_ and things might not work right away. The name of each chapter is the name of a YAML key, with user defined -values are in `<>`. For instance `jobs..runs-on` documents the following YAML equivalent where `job-id` is `myjob`: +values are in `< >`. For instance `jobs..runs-on` documents the following YAML equivalent where `job-id` is `myjob`: ```yaml jobs: diff --git a/plan.md b/plan.md index 98e34246..5d7c16bd 100644 --- a/plan.md +++ b/plan.md @@ -48,9 +48,9 @@ Page with all the more advanced concepts, for specific use-cases ### Actions guide -- [ ] How do actions work - - [ ] Which kinds -- [ ] How do you make your own +- [x] How do actions work + - [x] Which kinds +- [x] How do you make your own ### Workflow reference