mirror of
https://codeberg.org/Codeberg/Documentation.git
synced 2026-06-16 05:13:54 -07:00
Updated suggestions from Gusted and pat-s. Increased polish.
This commit is contained in:
Christopher A. Grant
cagrant
parent
be35012067
commit
258064e926
1 changed files with 34 additions and 19 deletions
|
|
@ -13,12 +13,17 @@ This guide will walk you through [setting up your own Woodpecker agent](https://
|
|||
|
||||
## Obtaining an agent token
|
||||
|
||||
{% admonition "info" "An agent may only be added to one user or org" %}
|
||||
|
||||
Any agent can only be assigned to either a single user or a single organization. This means that you will need to create multiple agents if you want to share resources with other users or organizations.
|
||||
|
||||
{% endadmonition %}
|
||||
|
||||
Before deploying the agent, you need to obtain an agent token from Codeberg's Woodpecker instance. The agent token is a secret shared between Codeberg's CI instance and your agent in order to facilitate the execution of workflows.
|
||||
|
||||
To do so, please follow the instructions immediately below for users, and follow the instructions below that for organizations.
|
||||
|
||||
|
||||
1. <a name="agent-instructions-1">Go to the agents page</a>
|
||||
1. Go to the agents page
|
||||
1. For users, go to the [Codeberg Woodpecker CI User Agent settings](https://ci.codeberg.org/user/agents)
|
||||
|
||||
2. For organizations:
|
||||
|
|
@ -48,9 +53,13 @@ The Woodpecker Agent is released as a docker image and as Linux distribution pac
|
|||
|
||||
The following configurations are modified to work with Codeberg's CI service from the official documentation. For more information on the specific variables available to configure, [please read the Woodpecker agent documentation](https://woodpecker-ci.org/docs/administration/configuration/agent).
|
||||
|
||||
### <a name="docker-compose">Creating an agent with Docker Compose</a>
|
||||
### Creating an agent with Docker Compose
|
||||
|
||||
Please note that agent secrets are added as environment variables in order to avoid leaking them.
|
||||
{% admonition "warning" "Agent tokens must be kept secret" %}
|
||||
|
||||
Tokens are added as the `WOODPECKER_AGENT_SECRET` environment variable to avoid leaks.
|
||||
|
||||
{% endadmonition %}
|
||||
|
||||
```yaml
|
||||
services:
|
||||
|
|
@ -70,7 +79,13 @@ volumes:
|
|||
woodpecker-agent-config:
|
||||
```
|
||||
|
||||
### Creating agents with Helm
|
||||
#### Automatically scaling your agents on demand
|
||||
|
||||
Woodpecker also has a container to automatically scale agents. This is not required for Kubernetes clusters. [Please read the autoscaler documentation for more information](https://woodpecker-ci.org/docs/administration/configuration/autoscaler)
|
||||
|
||||
### Managing agents with Kubernetes and Helm
|
||||
|
||||
Alternatively, Kubernetes can aid in managing your agents. It provides automatic scaling, metrics, topology management and whole host of other features that can be tuned for a particular project. For more details, [please see the Helm chart for Woodpecker Agents](https://github.com/woodpecker-ci/helm/blob/main/charts/woodpecker/charts/agent/README.md).
|
||||
|
||||
Only the agent chart is required.
|
||||
|
||||
|
|
@ -78,10 +93,6 @@ Only the agent chart is required.
|
|||
helm install woodpecker/agent oci://ghcr.io/woodpecker-ci/helm/woodpecker --version <VERSION>
|
||||
```
|
||||
|
||||
### Automatically scaling your agents on demand
|
||||
|
||||
Woodpecker also has software to automatically scale agents. [Please read the autoscaler documentation for more information](https://woodpecker-ci.org/docs/administration/configuration/autoscaler)
|
||||
|
||||
## Configuring workflows to use your agent
|
||||
|
||||
Now that you have added your agent to Codeberg CI, you can configure your workflows to use your new agent. This is recommended for resource intensive and long running jobs. This can also be used to create specialized agents that have access to hardware or other environmental configurations.
|
||||
|
|
@ -138,23 +149,25 @@ You can also add labels to the agent's configuration that can be used in workflo
|
|||
|
||||
For example, say you're creating an IoT project that needs a machine with a specific peripheral, such as a LoRa radio, for testing. You have an agent that has the module attached and you need a way to tell Woodpecker to use that particular machine. [Radio hardware often depends on what part of the world you're in,](https://en.wikipedia.org/wiki/ITU_Region) you also want specify where your agent is located.
|
||||
|
||||
Here is how to add the necessary environment variable to [an agent's docker compose script](#docker-compose) to label it in ITU Region 1 (Europe is in Region 1) with a lora module attached:
|
||||
Here is how to add the necessary environment variable to [an agent's docker compose script](#creating-an-agent-with-docker-compose) to label it in ITU Region 1 (Europe is in Region 1) with a lora module attached:
|
||||
|
||||
```yaml
|
||||
# Other agent configuration goes here...
|
||||
# Agent configuration goes here...
|
||||
environment:
|
||||
- WOODPECKER_AGENT_LABELS=location=region-1,peripheral=lora
|
||||
# Other enviroment variables variables go here...
|
||||
# Other enviroment variables go here...
|
||||
|
||||
```
|
||||
|
||||
You then use the following workflow to specify tests for those labels:
|
||||
|
||||
|
||||
```
|
||||
```yaml
|
||||
labels:
|
||||
location: region-1 # only select agents with a location of region-1
|
||||
peripheral: lora # only agents with the peripheral label set to lora will be selected
|
||||
# Only select agents with a location of `region-1`...
|
||||
location: region-1
|
||||
# ...and with the peripheral label set to `lora`
|
||||
peripheral: lora
|
||||
|
||||
steps:
|
||||
- name: test-debian
|
||||
|
|
@ -165,11 +178,13 @@ steps:
|
|||
- make test
|
||||
```
|
||||
|
||||
If you had a teammate running an agent in the Americas, you would then change the location label from region-1 to region-2 to run tests on their machines. If you wanted to run tests with a different peripheral, you'd change the peripheral label accordingly, etc.
|
||||
If you had a teammate running an agent in another continent, you would then change the location label in both the workflow and the agent from region-1 to region-2 or region-3 accordingly. If you wanted to run tests with a different peripheral, you'd change the peripheral label, etc.
|
||||
|
||||
## References
|
||||
|
||||
https://woodpecker-ci.org/docs/administration/general
|
||||
https://woodpecker-ci.org/docs/administration/installation/docker-compose
|
||||
https://woodpecker-ci.org/docs/usage/workflows
|
||||
- [Woodpecker General Administration Guide](https://woodpecker-ci.org/docs/administration/general)
|
||||
- [Woodpecker Docker Compose Installation Guide](https://woodpecker-ci.org/docs/administration/installation/docker-compose)
|
||||
- [Woodpecker Helm Installation Guide](https://woodpecker-ci.org/docs/administration/installation/helm-chart)
|
||||
- [Woodpecker Workflows Reference](https://woodpecker-ci.org/docs/usage/workflow)
|
||||
- [Woodpecker Workflow Syntax Reference](https://woodpecker-ci.org/docs/usage/workflow-syntax#label)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue