actions guide

docs/user/actions/actions.md

@@ -0,0 +1,83 @@
+---
+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.
+
+## Using Actions
+
+For example, to check out the contents of the repository you can use the [`actions/checkout`](https://code.forgejo.org/actions/checkout) action. To use it, add the following step to a job in your workflow:
+
+```yaml
+- name: Check out the repository
+  uses: actions/checkout@v4
+```
+
+This specifies that this step `uses` the action `actions/checkout`, version `v4`.
+
+An action like `actions/checkout@v4` will be prefixed with the `DEFAULT_ACTIONS_URL` ([https://data.forgejo.org/] by default) and checked out like a git repository. `v4` is the branch that will be checked out. You can also manually specify the fully qualified URL like this: `uses: https://data.forgejo.org/actions/checkout@v4`.
+
+The `DEFAULT_ACTIONS_URL` is set by your instance administrator. Because it may change at any time, **it is strongly recommended to use fully qualified URLs**.
+
+You can also load an action from a local directory instead of a remote repository. This is called a [local action](#local-actions).
+
+### Action inputs
+
+An Action can have parameters, called `input`s. 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:
+
+```yaml
+- 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](https://code.forgejo.org/forgejo/end-to-end/src/branch/main/actions/example-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`, `composite` and `docker`.
+
+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](#local-actions) for testing.
+
+### `actions.yml`
+
+The `actions.yml` file contains all the metadata for the action. It decides the name, description, inputs, outputs and steps taken.
+
+Take a look at this simple example:
+
+```yaml
+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'
+
+runs:
+  using: 'composite'
+  steps:
+    - run: echo ${{ inputs.message }} > message.txt
+```
+
+You can run any commands with the `run` key that you may also run normally in a workflow.

docs/user/actions/quick-start.md

@@ -48,7 +48,7 @@ Now we are ready to write a workflow file and add it to our repository:
 
 ## Using an action to check out your code
 
-An action is a reusable procedure for doing something in your CI workflow. In many ways, actions are similar to functions. To get the content of your repository into a workflow, we will be using the [`actions/checkout`](https://code.forgejo.org/actions/checkout) action. An action is simply a repository with some special files in it. For more information about how to use them and how to make your own, check out the [actions guide](TODO).
+An action is a reusable procedure for doing something in your CI workflow. In many ways, actions are similar to functions. To get the content of your repository into a workflow, we will be using the [`actions/checkout`](https://code.forgejo.org/actions/checkout) action. An action is simply a repository with some special files in it. For more information about how to use them and how to make your own, check out the [actions guide](../actions/).
 
 5. Add the following lines to the `demo.yaml` file, below `- run: echo All good!`:
 

docs/user/actions/reference.md

@@ -5,9 +5,13 @@ license: 'CC-BY-SA-4.0'
 
 This page contains the complete reference for Forgejo Actions workflow files. For a more information on what the different parts of these files mean and how to use the syntax, check the [basic concepts](../basic-concepts/).
 
+---
+
+Jump to the [context reference](#contexts).
+
 ## Workflow Syntax
 
-The syntax and semantics of the YAML file describing a `workflow` are _partially_ explained here. When an entry is missing the [GitHub Actions](https://docs.github.com/en/actions) documentation may be helpful because there are similarities. But there also are significant differences that require testing.
+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`:
@@ -245,7 +249,7 @@ The actual machine provided by the runner **entirely depends on how the runner w
 
 The list of available `labels` for a given repository can be seen in the `/{owner}/{repo}/settings/actions/runners` page.
 
-![a list of runners, with their associated labels](../_images/user/actions/list-of-runners.png)
+![a list of runners, with their associated labels](../../_images/user/actions/list-of-runners.png)
 
 If your job specifies a labal for which no runner is online, the job cannot be executed and your pipeline will halt until a runner with a matching label comes online. You will be able to see this in the Actions tab of your repository.
 
@@ -532,7 +536,7 @@ Check out the workflows in [example-if](https://code.forgejo.org/forgejo/end-to-
 
 Specifies the repository from which the `Action` will be cloned or a directory where it can be found.
 
-- Remote actions
+- **Remote actions**  
   A relative `Action` such as `uses: actions/checkout@v3` will clone the repository at the URL composed by prepending the default actions URL which is https://data.forgejo.org/. It is the equivalent of providing the fully qualified URL `uses: https://data.forgejo.org/actions/checkout@v3`. In other words the following:
 
   ```yaml
@@ -562,8 +566,7 @@ Specifies the repository from which the `Action` will be cloned or a directory w
   instead. Or even a repository that does not contain the intended
   action.
 
-- Local actions
-
+- **Local actions**  
   An action that begins with a `./` will be loaded from a directory
   instead of being cloned from a repository. The structure of the
   directory is otherwise the same as if it was located in a remote

docs/user/index.md

@@ -28,11 +28,12 @@ involved in running it on their machines.
   - [Clone & Commit via Web](https://docs.codeberg.org/git/clone-commit-via-web/)
   - [Tags and Releases](./releases/)
   - [Branch and tag protection](./protection/)
-  - Actions
+  - Actions CI
     - [Overview](./actions/overview/)
     - [Quick start guide](./actions/quick-start/)
     - [Basic concepts](./actions/basic-concepts/)
     - [Advanced features](./actions/advanced-features/)
+    - [Using Actions](./actions/actions/)
     - [References](./actions/reference/)
   - [Git blame](./blame/)
   - [README badges](./readme-badges/)