jmarya/knowledge
jmarya/knowledge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

add act

Browse source
This commit is contained in:
JMARyA 2024-04-26 08:11:55 +02:00
parent c9c4cda5ba
commit 599d81923a
Signed by: jmarya
GPG key ID: 901B2ADDF27C2263
1 changed files with 298 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

298
technology/applications/development/act.md Normal file
View file

@ -0,0 +1,298 @@
---
obj: application
repo: https://github.com/nektos/act
rev: 2024-04-25
---
# act
Act lets you run [GitHub Actions](../../dev/GitHub%20Actions.md) locally. It's also the base for the [Gitea](../web/Gitea.md) Actions Runner. When you run act it reads in your [GitHub Actions](../../dev/GitHub%20Actions.md) from `.github/workflows/` and determines the set of actions that need to be run. It uses the [Docker](../../tools/Docker.md) API to either pull or build the necessary images, as defined in your workflow files and finally determines the execution path based on the dependencies that were defined. Once it has the execution path, it then uses the [Docker](../../tools/Docker.md) API to run containers for each action based on the images prepared earlier. The [environment variables](../../linux/Environment%20Variables.md) and filesystem are all configured to match what [GitHub](GitHub.md) provides.
## Events
- `act` has basic event support, it will try to get as much information from local repository as possible, although this might be not enough for certain event types.
- Running `act` without any event name specified will run with event `push`.
- For a list of event names, please see [events that trigger workflows](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows "events-that-trigger-workflows").
---
- `push`:
```shell=sh
act push
```
> Runs all workflows with `push` event
---
- `pull_request`:
```shell=sh
act pull_request
```
- `schedule`:
```shell=sh
act schedule
```
To list all workflows for a given event, use `-l`/`--list`:
```shell=sh
act -l pull_request
```
### Using event file to provide complete event payload
If your workflow relies on passed event properties, you will have to provide required properties in the event file, example:
> To partially simulate `pull_request` event, you to provide at least `head_ref` and `base_ref`. This values can be later accessed via `${{ github.event.pull_request.<...> }}`
```json
{
"pull_request": {
"head": {
"ref": "sample-head-ref"
},
"base": {
"ref": "sample-base-ref"
}
}
}
```
> To partially simulate `push` event with a tag, you need to provide `ref` which will be accessible via `${{ github.event.ref }}`
```json
{
"ref": "refs/tags/this-is-a-tag"
}
```
## Workflows
> By default `act` will run **all** workflows in `.github/workflows`.
You can override that behaviour with `-W`/`--workflows` flag by specifying directory containing workflow files
```shell=sh
act -W '.github/workflows/'
```
> This example will run **all jobs** in **all workflows** in directory `.github/workflows` but only if the trigger event is `push`
---
or by specifying exact workflow file to run
```shell=sh
act -W '.github/workflows/checks.yml'
```
> This example will run **all jobs** in `.github/workflows/checks.yml` workflow file but only if it's trigger event is `push`
## Jobs
> By default `act` will run **all jobs** in **all workflows** that are triggerred by `push` event
```shell=sh
act -j 'test'
```
> This example will run **all jobs** named `test` in **all workflows** that trigger on `push` event
# Vars
To run `act` with repository variables that are acessible inside the workflow via ${{ vars.VARIABLE }}, you can enter them interactively or load them from a file. The following options are available for providing github repository variables:
- `act --var VARIABLE=somevalue` - use `somevalue` as the value for `VARIABLE`.
- `act --var-file my.variables` - load variables values from `my.variables` file.
- The variables file format is the same as `.env` format
## Secrets
To run `act` with secrets, you can enter them interactively, supply them as [environment variables](../../linux/Environment%20Variables.md) or load them from a file. The following options are available for providing secrets:
---
## **⚠ WARNING ⚠**
When inserting sensitive data in your terminal, it might be saved as plain text to history file provided by your shell. To mitigate that, prefix `act ...` command with a space (not all shells respect that) or use secure input (explained below) to insert data.
---
- `act -s MY_SECRET=somevalue` - use `somevalue` as the value for `MY_SECRET`.
- `act -s MY_SECRET` - check for an environment variable named `MY_SECRET` and use it if it exists. If the environment variable is not defined, prompt the user for a value. **This is recommended way of typing/pasting a secret into terminal, as `act` will provide secure input prompt for you to type/paste your secret which will not be saved in your shell history file.**
- `act --secret-file my.secrets` - load secrets values from `my.secrets` file.
- secrets file format is the same as `.env` format
### `GITHUB_TOKEN`
GitHub [automatically provides](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret) a `GITHUB_TOKEN` secret when running workflows inside [GitHub](GitHub.md). If your workflow fails with an error about `token`, it most likely requires `GITHUB_TOKEN` to be set up. If your workflow depends on this token, you need to create a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and pass it to `act` as a secret:
```bash
act -s GITHUB_TOKEN=[insert token or leave blank and omit equals for secure input]
```
If [GitHub CLI](https://cli.github.com/) is installed, the [`gh auth token`](https://cli.github.com/manual/gh_auth_token) command can be used to autmatically pass the token to act
```bash
act -s GITHUB_TOKEN="$(gh auth token)"
```
**WARNING**: `GITHUB_TOKEN` will be logged in shell history if not inserted through secure input or (depending on your shell config) the command is prefixed with a whitespace.
## `.env`/`.secrets` files structure
`.env` and `.secrets` files are using Ruby's gem [`dotenv`](https://github.com/bkeepers/dotenv) format through [`godotenv`](https://github.com/joho/godotenv) library
Example:
```shell
export MY_ENV='value'
PRIV_KEY="---...\nrandom text\n...---"
JSON="{\n\"name\": \"value\"\n}"
SOME_VAR=SOME_VALUE
```
To see more examples, go to [https://github.com/joho/godotenv/tree/v1.4.0/fixtures](https://github.com/joho/godotenv/tree/v1.4.0/fixtures)
## Skipping jobs
You cannot use the `env` context in job level if conditions, but you can add a custom event property to the `github` context. You can use this method also on step level if conditions.
```yml
on: push
jobs:
deploy:
if: ${{ !github.event.act }} # skip during local actions testing
runs-on: ubuntu-latest
steps:
- run: exit 0
```
And use this `event.json` file with act otherwise the Job will run:
```json
{
"act": true
}
```
Run act like
```sh
act -e event.json
```
_Hint: you can add / append `-e event.json` as a line into `./.actrc`_
## Skipping steps
Act adds a special environment variable `ACT` that can be used to skip a step that you don't want to run locally. E.g. a step that posts a Slack message or bumps a version number. **You cannot use this method in job level if conditions, see [Skipping jobs](https://nektosact.com/usage/index.html#skipping-jobs)**
```yml
- name: Some step
if: ${{ !env.ACT }}
run: |
...
```
## Pass Inputs to Manually Triggered Workflows
Example workflow file
```yaml
on:
workflow_dispatch:
inputs:
NAME:
description: "A random input name for the workflow"
type: string
SOME_VALUE:
description: "Some other input to pass"
type: string
jobs:
test:
name: Test
runs-on: ubuntu-latest
steps:
- name: Test with inputs
run: |
echo "Hello ${{ github.event.inputs.NAME }} and ${{ github.event.inputs.SOME_VALUE }}!"
```
### via input or input-file flag
- `act --input NAME=somevalue` - use `somevalue` as the value for `NAME` input.
- `act --input-file my.input` - load input values from `my.input` file.
- input file format is the same as `.env` format
### via JSON
Example JSON payload file conveniently named `payload.json`
```json
{
"inputs": {
"NAME": "Manual Workflow",
"SOME_VALUE": "ABC"
}
}
```
Command for triggering the workflow
```sh
act workflow_dispatch -e payload.json
```
## Specifying Matrix
You can selectively choose a subset of matrix options to run by specifying the `--matrix` flag. It will only run those matrix configurations which include your specified values.
Example workflow file
```yaml
name: matrix-with-user-inclusions
on: push
jobs:
build:
name: Matrix
runs-on: ubuntu-latest
steps:
- run: echo ${NODE_VERSION}
env:
NODE_VERSION: ${{ matrix.node }}
strategy:
matrix:
os: [ubuntu-18.04, macos-latest]
node: [4, 6, 8, 10]
exclude:
- os: macos-latest
node: 4
include:
- os: ubuntu-16.04
node: 10
```
In this case if we only wanted to run this workflow for node 8, then we would run `act push --matrix node:8`
This will trigger the workflow to use the following matrix configurations only:
- `os: ubuntu-18.04, node: 8`
- `os: macos-latest, node: 8`
Similarly if we just wanted to trigger this workflow for node 10 and macos-latest then we would run `act push --matrix node:10 --matrix os:macos-latest`.
This will trigger the workflow to use the following matrix configurations only:
- `os: macos-latest, node 10`
Note that using the `--matrix` flag you can't add new values (for e.g. running the above workflow for node 20). It will simply ignore it. Moreover, the `exclude` field in the workflow will take precedance over the `--matrix` flag (for e.g. running the above workflow for only macos-latest and node 4 will result in no matrix configuration being used)
## Action Offline Mode
If you want to speed up running act and using cached actions and container images you can enable this mode.
- stops pulling existing images
- stops failing if an action has been cached and you cannot connect to GitHub
- pulls non existent actions and images
- act will work offline if it has at least ran once while you are online
- get rid of unnecessary timeouts when you have an unstable connection to GitHub or Container registries
- workaround rate limit problems
```sh
act --action-offline-mode
```
or a `.actrc` file in your cwd like
```
--action-offline-mode
```