complete actions guide

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.

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'
 ---
 

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'
 ---
 

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'
 ---
 

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'
 ---
 

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.<job_id>.runs-on` documents the following YAML equivalent where `job-id` is `myjob`:
+values are in `< >`. For instance `jobs.<job_id>.runs-on` documents the following YAML equivalent where `job-id` is `myjob`:
 
 ```yaml
 jobs:

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