crowci/crow
crowci/crow
1
0
Fork 0
mirror of https://codeberg.org/crowci/crow.git synced 2025-04-18 04:44:01 +03:00
Code

docs: add various "usage" pages (#7)

Browse Source 
- add full codeberg pages support
- add new architecture diagram

Reviewed-on: https://codeberg.org/crowci/crow/pulls/7
Co-authored-by: pat-s <patrick.schratz@gmail.com>
Co-committed-by: pat-s <patrick.schratz@gmail.com>
This commit is contained in:
pat-s 2025-01-30 09:28:56 +00:00 committed by Patrick Schratz
parent e34ef5ed1c
commit b835a9ec7c
27 changed files with 466 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.cspell.json
View File

@ -251,6 +251,7 @@
"zerologger"
],
"ignorePaths": [
"*.drawio",
"*.excalidraw",
"*.svg",
"*_test.go",

1
.gitignore vendored
View File

@ -56,3 +56,4 @@ docs/venv
site/
.envrc
local.sh
*.bkp

2
Justfile
View File

@ -98,7 +98,7 @@ docs-serve:
fish -c 'source venv/bin/activate.fish && mkdocs --version && mkdocs serve'
docs-build:
fish -c 'source venv/bin/activate.fish && mkdocs --version && mkdocs build && cp -r site/* ~/git/codeberg.org/crowci/pages/ && cd ~/git/codeberg.org/crowci/pages/ && git add -A && git commit -m "update docs" && git push -u origin'
fish -c 'source venv/bin/activate.fish && mkdocs --version && mkdocs build && cp -r site/* ../pages/ && cd ~/git/codeberg.org/crowci/pages/ && mv domains .domains && git add -A && git commit -m "update docs" && git push -u origin'
docs-deploy:
fish -c 'source venv/bin/activate.fish && mkdocs --version && mkdocs gh-deploy'

1
docs/CNAME
View File

@ -1 +0,0 @@
crowci.dev

4
docs/configuration/architecture.drawio.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 274 KiB

32
docs/configuration/autoscaler.md
View File

@ -185,6 +185,36 @@ The values must be passed as a comma-separated list:
CROW_AGENT_ENV: CROW_HEALTHCHECK=false,CROW_LOG_LEVEL=debug
```
### Combining static and autoscaled agents
!!! information
A "static" agent is an agent which was **not** provisioned by Crow Autoscaler but through a different deployment.
It is always 24/7 for new builds and is the exact opposite of an autoscaling agent which is only available if task are to be processed and decommissioned afterwards.
In specific cases a combination of static and autoscaled agents can make sense and improve the overall capabilities of your CI environment.
One use case can be if there are many builds with low resource requirements.
In this case, it is not efficient to wait for the autoscaler to spin up a powerful machine which then processes these builds in a few seconds.
In such a situation, a static agent on a small host (e.g. next to the Crow CI server and autoscaler) can help to process such builds.
The autoscaler will then only kick in once this agent cannot process these builds.
To achieve this, there must a heuristic to decide if the static agent can process these builds in question.
Ideally this would be a mix of a dynamic rule based on resource requests and a static ones based on manual filters.
Currently, only the latter is available through "agent labels" (`CROW_AGENT_LABELS`).
This options allows to set filters which only process specific builds that match these.
For example, if the mentioned builds in question only occur within one repository, the agent can be passed the following label through the env var `CROW_AGENT_LABELS`:
```yaml
CROW_AGENT_LABELS: 'repo=<owner>/<repo>'
```
This configuration ensures that only builds from this specific repository are processed.[^1]
When a Crow CI autoscaler instance is active, it first checks whether an existing agent registered with the Crow CI server can handle a pending task.
If no suitable agent is available, the autoscaler will launch a new agent.
If an agent is available, no action is taken, and the build is handled by the static agent.
### GRPC proxy configuration
As mentioned above, the GRPC connection between the agent and the server needs to be secured.
@ -239,3 +269,5 @@ http:
servers:
- url: http://crow-server:9000
```
[^1]: Multiple labels can be passed, even of the same type.

8
docs/configuration/index.md
View File

@ -1,5 +1,13 @@
<!-- markdownlint-disable MD041 -->
# Configuration
All configuration is done through via environment variables.
These pages describe the configuration of **Server**, **Agent** and the _optional_ **Autoscaler** in greater detail.
A list of all existing environment variables is available at ["All environment variables"](env-vars.md).
![Agent creation](architecture.drawio.svg){ width="600", loading=lazy }
/// caption
Architectural overview of Crow CI components
///

3
docs/development/index.md
View File

@ -1,4 +1,7 @@
<!-- markdownlint-disable MD041 -->
WIP - Please see the [Woodpecker documentation](https://woodpecker-ci.org/docs/intro) in the meantime.
# Development
## Images

125
docs/diagrams/architecture.drawio Normal file
View File

@ -0,0 +1,125 @@
<mxfile host="Electron" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/26.0.9 Chrome/128.0.6613.186 Electron/32.2.5 Safari/537.36" version="26.0.9">
<diagram name="Page-1" id="b_jqith2f1Qkqu7QCLW4">
<mxGraphModel dx="2184" dy="1220" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1050" pageHeight="1000" math="0" shadow="0">
<root>
<mxCell id="0" />
<mxCell id="1" parent="0" />
<mxCell id="6NUMAyw0pABXv4PjhY65-1" value="" style="rounded=1;whiteSpace=wrap;html=1;strokeColor=light-dark(#f47003, #5f5f5f);fillColor=none;textShadow=0;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="160" y="230" width="350" height="130" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-3" value="Webhooks" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="390" y="240" width="90" height="40" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-5" value="Server" style="rounded=0;whiteSpace=wrap;html=1;strokeColor=light-dark(#000000,#5F5F5F);strokeWidth=2;labelBackgroundColor=#F47003;fillColor=#F47003;" vertex="1" parent="1">
<mxGeometry x="313.75" y="200" width="52.5" height="20" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-8" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=1;entryY=0.5;entryDx=0;entryDy=0;strokeColor=default;curved=0;flowAnimation=0;startArrow=block;startFill=1;endArrow=block;endFill=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" source="6NUMAyw0pABXv4PjhY65-6" target="6NUMAyw0pABXv4PjhY65-3">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="500" y="145" />
<mxPoint x="500" y="260" />
</Array>
</mxGeometry>
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-9" value="Events: push, tag, pull_request, manual, etc." style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];labelBackgroundColor=none;" vertex="1" connectable="0" parent="6NUMAyw0pABXv4PjhY65-8">
<mxGeometry x="-0.2111" relative="1" as="geometry">
<mxPoint x="-3" y="14" as="offset" />
</mxGeometry>
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-6" value="Forgejo, Gitea, GitHub, GitLab, Bitbucket" style="rounded=1;whiteSpace=wrap;html=1;strokeColor=light-dark(#FF6666,#5F5F5F);fillColor=none;labelPosition=center;verticalLabelPosition=middle;align=center;verticalAlign=middle;textShadow=0;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="215" y="120" width="250" height="50" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-7" value="Forge" style="rounded=0;whiteSpace=wrap;html=1;strokeColor=light-dark(#000000,#5F5F5F);dashed=1;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="315" y="90" width="50" height="20" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-11" style="edgeStyle=orthogonalEdgeStyle;shape=connector;curved=0;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;strokeColor=default;align=center;verticalAlign=middle;fontFamily=Helvetica;fontSize=11;fontColor=default;labelBackgroundColor=default;startArrow=block;startFill=1;endArrow=block;endFill=1;flowAnimation=0;exitX=0;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" source="6NUMAyw0pABXv4PjhY65-10" target="6NUMAyw0pABXv4PjhY65-6">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="255" y="260" />
<mxPoint x="255" y="190" />
<mxPoint x="190" y="190" />
<mxPoint x="190" y="145" />
</Array>
</mxGeometry>
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-12" value="User login" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontFamily=Helvetica;fontSize=11;fontColor=default;labelBackgroundColor=none;" vertex="1" connectable="0" parent="6NUMAyw0pABXv4PjhY65-11">
<mxGeometry x="-0.13" y="1" relative="1" as="geometry">
<mxPoint x="-30" y="9" as="offset" />
</mxGeometry>
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-10" value="Authentication" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="280" y="240" width="90" height="40" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-13" value="UI" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="280" y="300" width="90" height="40" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-14" value="GRPC" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="390" y="300" width="90" height="40" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-25" style="edgeStyle=orthogonalEdgeStyle;shape=connector;curved=0;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=default;align=center;verticalAlign=middle;fontFamily=Helvetica;fontSize=11;fontColor=default;labelBackgroundColor=default;startArrow=block;startFill=1;endArrow=block;endFill=1;flowAnimation=0;exitX=0.514;exitY=-0.045;exitDx=0;exitDy=0;exitPerimeter=0;" edge="1" parent="1" source="6NUMAyw0pABXv4PjhY65-39" target="6NUMAyw0pABXv4PjhY65-13">
<mxGeometry relative="1" as="geometry">
<mxPoint x="284" y="400" as="sourcePoint" />
</mxGeometry>
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-21" style="edgeStyle=orthogonalEdgeStyle;shape=connector;curved=0;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;strokeColor=default;align=center;verticalAlign=middle;fontFamily=Helvetica;fontSize=11;fontColor=default;labelBackgroundColor=default;startArrow=block;startFill=1;endArrow=block;endFill=1;flowAnimation=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" edge="1" parent="1" source="6NUMAyw0pABXv4PjhY65-17" target="6NUMAyw0pABXv4PjhY65-14">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="640" y="470" />
<mxPoint x="435" y="470" />
</Array>
</mxGeometry>
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-22" value="&lt;br&gt;Communication via GRPC&lt;br&gt;(Port 9000)&lt;br&gt;&lt;br&gt;Receives: Workflows&lt;br&gt;Returns: Logs and (exit) status&lt;div&gt;&lt;br&gt;&lt;/div&gt;" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];fontFamily=Helvetica;fontSize=11;fontColor=default;labelBackgroundColor=none;labelBorderColor=none;textShadow=0;" vertex="1" connectable="0" parent="6NUMAyw0pABXv4PjhY65-21">
<mxGeometry x="0.1782" y="1" relative="1" as="geometry">
<mxPoint x="52" y="-52" as="offset" />
</mxGeometry>
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-17" value="" style="rounded=1;whiteSpace=wrap;html=1;strokeColor=light-dark(#6600CC,#5F5F5F);fillColor=none;labelPosition=center;verticalLabelPosition=middle;align=center;verticalAlign=middle;textShadow=0;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="540" y="230" width="200" height="130" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-18" value="&lt;span&gt;Agent&lt;/span&gt;" style="rounded=0;whiteSpace=wrap;html=1;strokeColor=light-dark(#000000,#5F5F5F);strokeWidth=2;align=center;verticalAlign=middle;fontFamily=Helvetica;fontSize=12;fontColor=light-dark(#ffffff, #ededed);labelBackgroundColor=none;fillColor=#6600CC;" vertex="1" parent="1">
<mxGeometry x="620" y="200" width="50" height="20" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-19" value="Backend&lt;div&gt;(Docker, Kubernetes)&lt;/div&gt;" style="rounded=1;whiteSpace=wrap;html=1;strokeColor=light-dark(#00CCCC,#5F5F5F);fillColor=none;labelPosition=center;verticalLabelPosition=middle;align=center;verticalAlign=middle;gradientColor=none;" vertex="1" parent="1">
<mxGeometry x="570" y="295" width="140" height="50" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-20" value="Executes workflows via the chosen backend" style="rounded=0;whiteSpace=wrap;html=1;strokeColor=none;fillColor=none;fontFamily=Helvetica;fontSize=11;fontColor=default;labelBackgroundColor=none;" vertex="1" parent="1">
<mxGeometry x="575" y="240" width="130" height="50" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-35" style="edgeStyle=orthogonalEdgeStyle;shape=connector;curved=0;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=default;align=center;verticalAlign=middle;fontFamily=Helvetica;fontSize=11;fontColor=default;labelBackgroundColor=default;startArrow=block;startFill=1;endArrow=block;endFill=1;flowAnimation=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" edge="1" parent="1" source="6NUMAyw0pABXv4PjhY65-26" target="6NUMAyw0pABXv4PjhY65-32">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="40" y="380" />
<mxPoint x="140" y="380" />
<mxPoint x="140" y="295" />
</Array>
</mxGeometry>
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-36" value="Acts with User API token&lt;br&gt;1. Spins up server&lt;br&gt;2. Creates agent&lt;br&gt;3. Shuts down agent&lt;div&gt;4. Removes server&lt;/div&gt;" style="edgeLabel;html=1;align=left;verticalAlign=middle;resizable=0;points=[];fontFamily=Helvetica;fontSize=11;fontColor=default;labelBackgroundColor=none;" vertex="1" connectable="0" parent="6NUMAyw0pABXv4PjhY65-35">
<mxGeometry x="-0.353" y="1" relative="1" as="geometry">
<mxPoint x="-49" y="44" as="offset" />
</mxGeometry>
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-26" value="Can provision agents dynamically&lt;br&gt;&amp;nbsp;based on pending workflows" style="rounded=1;whiteSpace=wrap;html=1;strokeColor=light-dark(#009900,#5F5F5F);fillColor=none;labelPosition=center;verticalLabelPosition=middle;align=center;verticalAlign=middle;textShadow=0;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="-50" y="230" width="180" height="130" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-27" value="Autoscaler" style="rounded=0;whiteSpace=wrap;html=1;strokeColor=light-dark(#000000,#5F5F5F);strokeWidth=2;align=center;verticalAlign=middle;fontFamily=Helvetica;fontSize=12;fontColor=light-dark(#ffffff, #ededed);labelBackgroundColor=none;fillColor=#009900;" vertex="1" parent="1">
<mxGeometry x="15" y="200" width="70" height="20" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-32" value="API" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="180" y="275" width="90" height="40" as="geometry" />
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-40" style="edgeStyle=orthogonalEdgeStyle;shape=connector;curved=0;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;strokeColor=default;align=center;verticalAlign=middle;fontFamily=Helvetica;fontSize=11;fontColor=default;labelBackgroundColor=default;startArrow=block;startFill=1;endArrow=block;endFill=1;flowAnimation=0;" edge="1" parent="1" source="6NUMAyw0pABXv4PjhY65-39" target="6NUMAyw0pABXv4PjhY65-32">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="225" y="423" />
</Array>
</mxGeometry>
</mxCell>
<mxCell id="6NUMAyw0pABXv4PjhY65-39" value="User" style="points=[];aspect=fixed;html=1;align=center;shadow=0;dashed=0;fillColor=#00CCCC;strokeColor=none;shape=mxgraph.alibaba_cloud.user;fontFamily=Helvetica;fontSize=11;fontColor=default;labelBackgroundColor=default;labelPosition=center;verticalLabelPosition=bottom;verticalAlign=top;" vertex="1" parent="1">
<mxGeometry x="302" y="400" width="46" height="46" as="geometry" />
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>

2
docs/domains Normal file
View File

@ -0,0 +1,2 @@
crowci.dev
crowci.codeberg.page

3
docs/ecosystem/community.md
View File

@ -1,2 +1,3 @@
<!-- markdownlint-disable MD041 -->
WIP
WIP - Please see the [Woodpecker documentation](https://woodpecker-ci.org/docs/intro) in the meantime.

2
docs/ecosystem/index.md
View File

@ -1,2 +1,4 @@
<!-- markdownlint-disable MD041 -->
# Ecosystem
WIP - Please see the [Woodpecker documentation](https://woodpecker-ci.org/docs/intro) in the meantime.

3
docs/ecosystem/socials.md
View File

@ -0,0 +1,3 @@
<!-- markdownlint-disable MD041 -->
WIP - Please see the [Woodpecker documentation](https://woodpecker-ci.org/docs/intro) in the meantime.

23
docs/installation/migration.md
View File

@ -1,2 +1,23 @@
<!-- markdownlint-disable MD041 -->
WIP
## Woodpecker
Crow CI is currently a soft-fork of Woodpecker CI.
This means it is compatible with Woodpecker in terms of
- API usage
- Plugin usage
- most configuration options
Crow CI 3.0 has support for Woodpecker-prefixed env vars (`WOODPECKER_`) which should allow a seamless migration from Woodpecker (3.0).
Moving on from 3.0, it can't be guaranteed that all new Woodpecker features and env vars will be supported or available at all.
Crow CI has it's own env vars prefixed with `CROW_`.
For now, these are identical to the Woodpecker ones.
Additional/alternate names might be introduced over time.
## Drone
As Woodpecker itself is a fork of Drone and aims to keep compatibility for Drone (mainly to allow Drone plugin usage), the same applies to Crow CI.
Though it should be kept in mind that the initial fork of Drone was in 2019 and since then Woodpecker has evolved continuously while both Drone and its plugins only received maintenance updates, if at all.
If you are still using Drone CI and are thinking about switching, now would be a good time!

2
docs/plugins/index.md
View File

@ -1,2 +1,4 @@
<!-- markdownlint-disable MD041 -->
# Plugins
WIP - Please see the [Woodpecker documentation](https://woodpecker-ci.org/docs/intro) in the meantime.

4
docs/usage/advanced.md Normal file
View File

@ -0,0 +1,4 @@
<!-- markdownlint-disable MD041 -->
# Advanced
WIP - Please see the [Woodpecker documentation](https://woodpecker-ci.org/docs/intro) in the meantime.

4
docs/usage/cron.md Normal file
View File

@ -0,0 +1,4 @@
<!-- markdownlint-disable MD041 -->
# CRON
WIP - Please see the [Woodpecker documentation](https://woodpecker-ci.org/docs/intro) in the meantime.

3
docs/usage/deployment.md
View File

@ -0,0 +1,3 @@
<!-- markdownlint-disable MD041 -->
WIP - Please see the [Woodpecker documentation](https://woodpecker-ci.org/docs/intro) in the meantime.

3
docs/usage/env-vars-usage.md
View File

@ -0,0 +1,3 @@
<!-- markdownlint-disable MD041 -->
WIP - Please see the [Woodpecker documentation](https://woodpecker-ci.org/docs/intro) in the meantime.

2
docs/usage/index.md
View File

@ -1,2 +1,4 @@
<!-- markdownlint-disable MD041 -->
# Usage
WIP - Please see the [Woodpecker documentation](https://woodpecker-ci.org/docs/intro) in the meantime.

85
docs/usage/pipelines.md
View File

@ -0,0 +1,85 @@
## Overview
A pipeline consists of **one or more** workflows.
A workflow consist of **one or more** steps.
!!! important
Pipeline > Workflow > Step
A YAML file in `.crow/` defines _one workflow_.
The following file tree would consist of _four_ workflows:
```tree
.crow/
├── build.yaml
├── deploy.yaml
├── lint.yaml
└── test.yaml
```
Each workflow can be
- run individually
- run in parallel
- run in sequence of others
depending on the configuration of the respective _event triggers_ and `depends_on` configuration in each individual workflow.
!!! important
Each workflow is isolated from other workflows with respect to its working directory and file access.
*Steps* within a workflow have access to the same files.
## Execution control
By default, all workflows start in parallel if they have matching event triggers.
An execution order can be enforced by using `depends_on`:
```yaml hl_lines="7 8 9 10"
steps:
- name: deploy
image: <image>:<tag>
commands:
- some command
depends_on:
- lint
- build
- test
```
This keyword also works for dependency resolution with steps.
!!! note
Workflows which depend on others only start if the dependent ones finished successfully.
A workflow can be forced to execute no matter the exit status of other workflows by setting
```yaml
runs_on: [ success, failure ]
```
## Event triggers
Event triggers are _mandatory_ and define under which conditions a workflow is executed.
At the very least one even trigger must be specified, for example to execute the pipeline on a `push` event:
```yaml
when:
event: push
```
Typically, you want to use a more fine-grained logic including more events, for example triggering a workflow for `pull_request` events and pushes to the default branch of the repository:
```yaml
when:
- event: pull_request
- event: push
branch: ${CI_REPO_DEFAULT_BRANCH}
```
There are more ways to define event triggers using both list and map notation.
Please see FIXME for all available options.
## Matrix workflows

3
docs/usage/registries.md
View File

@ -0,0 +1,3 @@
<!-- markdownlint-disable MD041 -->
WIP - Please see the [Woodpecker documentation](https://woodpecker-ci.org/docs/intro) in the meantime.

13
docs/usage/repo-settings.md Normal file
View File

@ -0,0 +1,13 @@
<!-- markdownlint-disable MD041 -->
WIP - Please see the [Woodpecker documentation](https://woodpecker-ci.org/docs/intro) in the meantime.
# Repository settings
## Approval requirements
## Privileges & Security
## Custom trusted clone plugins
## Allow deployments

134
docs/usage/secrets.md
View File

@ -0,0 +1,134 @@
<!-- markdownlint-disable MD041 -->
# Secrets
## General
Crow CI provides an integrated secret store.
These secrets can be passed securely to individual steps using the `from_secret` keyword.
Three different levels of secrets are available:
1. **Repository secrets**: Available to all workflows of a repository.
1. **Organization secrets**: Available to all workflows of an organization.
1. **Global secrets**: Global secret are available to all pipelines of the entire Crow CI instance.
Can only be set by instance administrators.
!!! note
If a secret is defined at multiple levels, repository secrets take precedence over organization secrets, which in turn override global secrets, following this hierarchy.
!!! tip
In addition to native secrets, external secret providers can be utilized by interacting with them directly within steps.
Access to these external providers can be configured using Crow CI secrets.
!!! warning
Crow CI masks native secrets in the log output, but it cannot do so for external secrets.
As a result, external secrets may be exposed in the logs!
## Defining secrets
Secrets are defined using the `from_secret:` keyword in the `environment:` section:
```yaml hl_lines="7 8"
steps:
- name: 'step name'
image: registry/repo/image:tag
commands:
- echo "The secret is $TOKEN_ENV"
environment:
TOKEN_ENV:
from_secret: secret_token
```
Secrets names can be uppercase or lowercase.
The same applies to the environment variables they are assigned to.
Secrets can also be used for `settings:` in plugins:
```yaml hl_lines="7 8"
steps:
- name: 'step name'
image: registry/repo/image:tag
commands:
- echo "The secret is $TOKEN_ENV"
settings:
TOKEN:
from_secret: secret_token
```
!!! important
Parameter expressions like secrets undergo pre-processing, meaning they are evaluated before the workflow starts.
If secrets are to be used in commands directly, they must be properly escaped (using `$$`) to ensure correct handling.
```yaml hl_lines="5"
steps:
- name: docker
image: docker
commands:
- echo $${TOKEN_ENV}
environment:
TOKEN_ENV:
from_secret: secret_token
```
## Filtering
To prevent secrets from potential abuse in arbitrary steps, they can be limited to specific plugins in the repository settings.
Plugins offer the advantage of not being able to execute arbitrary commands (in contrast to normal steps), and by this inherently prohibit the possibility of exposing secrets in any kind of way.
!!! important
Filtering only works for plugins, not for arbitrary images.
Applying it to the latter would not make sense as malicious actors could simply use the specified image to exploit the secret.
## Adding secrets via CLI
Secrets can also be added via the CLI.
By default, secrets will be available without any restriction:
```yaml
crow-cli repo secret add \
--repository octocat/hello-world \
--name my_secret \
--value <value>
```
Limit it to a specific plugin:
```yaml hl_lines="3"
crow-cli secret add \
--repository octocat/hello-world \
--image woodpeckerci/plugin-s3 \
--name aws_access_key_id \
--value <value>
```
The `--image` can also be passed multiple times.
Limit to specific events:
```yaml hl_lines="4 5 6"
crow-cli repo secret add \
--repository octocat/hello-world \
--image woodpeckerci/plugin-s3 \
--event pull_request \
--event push \
--event tag \
--name aws_access_key_id \
--value <value>
```
Secret can also be loaded from a file on disk.
This can be useful for multi-line secrets like SSH keys:
```yaml hl_lines="4"
crow-cli repo secret add \
-repository octocat/hello-world \
-name ssh_key \
-value @/root/ssh/id_rsa
```

3
docs/usage/volumes.md Normal file
View File

@ -0,0 +1,3 @@
<!-- markdownlint-disable MD041 -->
WIP - Please see the [Woodpecker documentation](https://woodpecker-ci.org/docs/intro) in the meantime.

4
docs/usage/workflow-syntax.md
View File

@ -1 +1,3 @@
## Matrix workflows
<!-- markdownlint-disable MD041 -->
WIP - Please see the [Woodpecker documentation](https://woodpecker-ci.org/docs/intro) in the meantime.

2
mkdocs.yaml
View File

@ -123,7 +123,7 @@ nav:
- usage/index.md
- Pipelines & Workflows: usage/pipelines.md
- Workflow syntax: usage/workflow-syntax.md
- Repository settings: usage/settings.md
- Repository settings: usage/repo-settings.md
- Secrets: usage/secrets.md
- Cron jobs: usage/cron.md
- Deployment jobs: usage/deployment.md