README ¶
Reeve CI / CD - Gitea Plugin
This is a Reeve plugin for integrating a Gitea server.
Configuration
This plugin applies to and is expected to be used in common Git environments.
This plugin supports promoting actions to the WebUI plugin if present.
Actions can be logically grouped by using colons as separators, e.g. parent-group:child-group:name
.
To hide actions from the WebUI, you can prefix them with a colon, e.g. :name
.
Gitea
An API token is required for this plugin. Please select an user which has access to all relevant repositories.
You need to setup webhooks in your Gitea instance if you want to trigger pipelines on pushes.
The webhook URL should look like http(s)://<YOUR_REEVE_SERVER>:<PORT>/api/v1/message?token=<YOUR-MESSAGE-SECRET>&target=gitea&type=webhook
.
For most configurations, you will want to give Reeve access to only a subset of the projects on your Git server. To do this, you just need to assign the user for whom you are generating the API token to the appropriate repositories. You can also enable access for a whole organization by adding the user to the organization instead of the individual repositories. However, note that the user must have write access in order to be recognized as an assignee.
If you want to enable Reeve for the entire Git server instead, set the UNRESTRICTED
setting to true
and grant administrative access to the token user.
Settings
Settings can be provided to the plugin through environment variables set to the reeve server.
Settings for this plugin should be prefixed by REEVE_PLUGIN_GITEA_
.
Settings may also be shared between plugins by prefixing them with REEVE_SHARED_
instead.
ENABLED
-true
enables this pluginURL
(required) - Gitea base URL (usuallyhttps://git.your.domain
). This is used for accessing Gitea from the plugin, checking repository URL validity (unlessPUBLIC_URL
is configured) and for cloning repositories when running pipelines (unlessCLONE_URL
is configured).CLONE_URL
- Optional Gitea base URL that workers should use for cloning repositories, if different thanURL
. This setting should be used if your workers cannot access Gitea overURL
.PUBLIC_URL
- Optional Gitea base URL for checking repository URL validity, if different thanURL
. This is the URL that Gitea is publicly available at (this is configured in Gitea asROOT_URL
). This setting should be used if the plugin accesses Gitea from another URL than your users do. Note that Reeve won't be able to run any Gitea pipelines if this does not match what the Gitea ReST API returns.TOKEN
(required) - Gitea API TokenUNRESTRICTED
- Do not restrict search by userTASK_DOMAINS
- Space separated list of task domains. Each entry should have the formdomain
ordomain:prefix
, where domain is the name of the task domain and prefix is an optional prefix for the domain's tasks. If an entry contains multiple colons, the first colon is used as the separator.TRUSTED_DOMAINS
- Space separated list of task domains to trust. A task is considered to be trusted if it has a task domain specified and if the task domain matches one of the options provided by this setting.TRUSTED_TASKS
- Space separated list of tasks to trust. A task is considered to be trusted if it matches one of the options provided by this setting.SETUP_GIT_TASK
(required) - Task to be used for setting up pipelinesSECRET_KEY
(required) - Passphrase for encrypting secretsDISCOVERY_SCHEDULE
(defaults to"0 12 * * *"
) - Cron expression which specifies how often the Git server should be fully scanned. The server is also scanned when the plugin starts, and single repositories are updated when a corresponding webhook is received. Scheduled server scanning can be disabled by setting the option tonever
.
Messages
This plugin supports two types of messages:
Gitea webhooks
Gitea webhooks allow Reeve to run pipelines whenever a specific action is executed in your Git repositories.
You can skip pipeline execution by adding [skip ci]
or [ci skip]
anywhere in your commit message.
Query parameters:
token
- Reeve message secrettarget
- Must begitea
type
- Must bewebhook
Content:
See Gitea Webhook API
Actions
Actions can be used to execute pipelines via HTTP requests to the message endpoint.
Unless the UNRESTRICTED
setting is enabled, the execution of actions is restricted to projects to which the token user is assigned.
Query parameters:
token
- Reeve message secrettarget
- Must begitea
type
- Must beaction
action
- Action to be passed to pipeline factssearch
- Search term for limiting repository discovery
Actions can also be triggered via the CLI API:
reeve ask gitea action <action> [<search> ...]
Facts
The following facts are provided:
trigger
- [push
,commit
] or [push
,tag
] or [action
]action
- Specified action - Only available foraction
triggersref
- Git ref - Ref of the head commit or tag, e.g.refs/heads/main
orrefs/tags/v1.0.0
branch
- Git branch - Not available fortag
triggersfile
- Affected file(s) - Only available forcommit
triggerstag
- Git tag - Only available fortag
triggersrepository
- Full name of the repository, e.g.ReeveCI/Reeve
Using the
file
fact when force-pushing changes may result in unexpected behavior, as monitoring file changes is limited to commits that are not already known to Gitea. If, for example, a branch was reset to a previous commit and then force-pushed, no new commits would be pushed, so no files would be marked as changed, even if the working directory has changed.
Default conditions
If not specified otherwise, pipelines are limited to commits on the repository's default branch.
This can be changed by adding conditions for trigger
and branch
in your pipelines when
section.
Since it is usually undesirable to execute a pipeline without restriction for all possible actions if the action
trigger is set, this is prevented by default.
Therefore actions must always be specified explicitely by also adding conditions for action
.
Pipeline definition
Pipelines and environment variables are defined in the file /.reeve.yaml
in a repository's root directory (or /.reeve.yml
).
A pipeline file can contain multiple YAML documents, which are divided with ---
, e.g.:
---
type: variable
name: MY_VAR
value: some-value
---
type: pipeline
name: hello-world
steps: []
Templating
Pipeline files can use Go templating to automatically generate repetitive pipelines.
To enable the feature for a file, append the extension .tmpl
to its name (e.g. /.reeve.yaml.tmpl
).
Files with the .tmpl
extension must be valid Go templates,
and can use sprig template functions.
File Includes
---
type: include
path: path/to/file.yaml
---
type: include
path: path/to/file.yaml.tmpl
templateData:
any:
- thing
The file to be included must end with one of the extensions .yaml
, .yml
, .yaml.tmpl
or .yml.tmpl
.
If you include a template file, the key templateData
can be used to provide parameters to your template as .
(dot).
The key templateData
may contain any valid YAML.
Variables
---
type: variable
name: MY_ENV
value: some-value
Secrets
---
type: secret
name: MY_ENV
value: some-encrypted-value
Values can be encrypted using the encrypt
CLI command:
reeve ask gitea encrypt '<secret value>'
Encryption takes place on the server, so make sure to use a secure connection between reeve-cli and the server. That is, use TLS with a valid certificate and do not set the insecure
option.
Cron schedules
---
type: trigger
cron: * * * * *
action: some-action
The specified action is triggered based on the schedule.
Cron syntax:
* * * * *
^ ^ ^ ^ ^
| | | | |
| | | | +----- day of week (0-6) (Sunday=0)
| | | +------- month (1-12)
| | +--------- day of month (1-31)
| +----------- hour (0-23)
+------------- min (0-59)
Examples:
* * * * *
- Run on every minute0 0 * * 1
- Run at midnight on every Monday* 10,15,19 * * *
- run at 10:00, 15:00 and 19:001-15 * * * *
- run at 1, 2, 3...15 minute of each hour*/2 * * * *
- run every two minutes1-59/2 * * * *
- run every two minutes, but on odd minutes
Details: https://github.com/mileusna/crontab
Pipelines
---
type: pipeline
name: hello-world
description: |
# Markdown description for your pipeline
when:
some-fact:
include: [value]
exclude: [value]
include env: [MY_ENV]
exclude env: [MY_ENV]
match: [^regexp$]
mismatch: [^regexp$]
env MY_ENV:
steps:
- name: greet
stage: greeting
task: hello-world
command: ["sh", "-c", "echo hello-world"]
input: |
data to be sent
to stdin
directory: /host/directory/to/be/mounted
user: "user-or-uid"
params:
PARAM1: some-value
PARAM2: { env: MY_ENV, replace: [/regexp/replacement/] }
PARAM3: { var: MY_VAR, replace: [] }
ignoreFailure: true
when:
fact:
include: [value]
exclude: [value]
include env: [MY_ENV]
exclude env: [MY_ENV]
include var: [MY_ENV]
exclude var: [MY_ENV]
match: [^regexp$]
mismatch: [^regexp$]
env MY_ENV:
var MY_VAR:
If a valid README file is found in the root of the repository, it is appended to all pipelines' descriptions.
You can disable this for individual pipelines by suffixing your description with [no readme]
.
Documentation ¶
There is no documentation for this package.