mash-playbook/docs/services/woodpecker-ci.md

Woodpecker CI

This playbook can install and configure Woodpecker CI for you.

Woodpecker CI is a Continuous Integration engine which can build and deploy your code automatically after pushing to a Gitea repository.

A Woodpecker CI installation contains 2 components:

• one Woodpecker CI server (web interface, central management node)
• one or more Woodpecker CI agent instances (which run your CI jobs)

It's better to run the agent instances elsewhere (not on the source-control server or a server serving anything of value) - on a machine that doesn't contain sensitive data.

Small installations which only run trusted CI jobs can afford to run an agent instance on the source-control server itself.

Woodpecker CI Server

Dependencies

This service requires the following other services:

• a Postgres database
• a Traefik reverse-proxy server

Configuration

To enable this service, add the following configuration to your vars.yml file and re-run the installation process:

########################################################################
#                                                                      #
# woodpecker-ci-server                                                 #
#                                                                      #
########################################################################

devture_woodpecker_ci_server_enabled: true

devture_woodpecker_ci_server_hostname: mash.example.com

devture_woodpecker_ci_server_path_prefix: /ci

# Generate this secret with `openssl rand -hex 32`
#
# Note that this playbook only supports agent-specific secrets, which
# means that if you choose to share this secret with an agent, the
# server will register it as a non-persistent agent.
#
# See the definition of
# devture_woodpecker_ci_agent_config_agent_secret below for more details.
devture_woodpecker_ci_server_config_agent_secret: ''

devture_woodpecker_ci_server_config_admins: [YOUR_USERNAME_HERE]

# Add one or more usernames that match your version control system (e.g. Gitea) below.
# These users will have admin privileges upon signup.
devture_woodpecker_ci_server_config_admins:
  - YOUR_USERNAME_HERE
  - ANOTHER_USERNAME_HERE

# Uncomment the line below if you'll be running Woodpecker CI agents on remote machines.
# If you'll only run agents on the same machine as the server, you can keep gRPC expose disabled.
# devture_woodpecker_ci_server_container_labels_traefik_grpc_enabled: true

########################################################################
#                                                                      #
# /woodpecker-ci-server                                                #
#                                                                      #
########################################################################

In the example configuration above, we configure the service to be hosted at https://mash.example.com/ci.

If you want to host the service at the root path, remove the devture_woodpecker_ci_server_path_prefix variable override.

Gitea Integration

The Woodpecker CI server can integrate with Gitea using the following additional vars.yml configuration:

devture_woodpecker_ci_server_provider: gitea

# We must use the public URL here, because it's also used for login redirects
devture_woodpecker_ci_server_config_gitea_url: "{{ gitea_config_root_url }}"

# Populate these with the OAuth 2 application information
# (see the Gitea configuration section above)
devture_woodpecker_ci_server_config_gitea_client: GITEA_OAUTH_CLIENT_ID_HERE
devture_woodpecker_ci_server_config_gitea_secret: GITEA_OAUTH_CLIENT_SECRET_HERE

devture_woodpecker_ci_server_container_add_host_domain_name: "{{ gitea_hostname }}"
devture_woodpecker_ci_server_container_add_host_ip_address: "{{ ansible_host }}"

To integrate with version-control systems other than Gitea (e.g. Forgejo), you'll need similar configuration.

Usage

After installation, you should be able to access the Woodpecker CI server instance at https://mash.DOMAIN/ci (matching the devture_woodpecker_ci_server_hostname and devture_woodpecker_ci_server_path_prefix values configured in vars.yml).

The Log in button should take you to Gitea, where you can authorize Woodpecker CI with the OAuth 2 application.

Follow the official Woodpecker CI Getting started documentation for additional usage details.

Woodpecker CI Agent

As mentioned above, unless you completely trust your CI workloads, it's best to run the Woodpecker CI Agent on another machine.

Dependencies

This service requires the following other services:

• a Woodpecker CI Server - installed via this playbook or otherwise

Configuration

########################################################################
#                                                                      #
# woodpecker-ci-agent                                                  #
#                                                                      #
########################################################################

devture_woodpecker_ci_agent_enabled: true

# If the agent runs on the same machine as the server, enabling the agent
# is everything you need. The agent and server will be wired automatically.
#
# Otherwise, you'll need to configure the variables below:

# This needs to point to the server's gRPC host:port.
# If your Woodpecker CI Server is deployed using this playbook, its
# gRPC port will likely be 443.  E.g., ci.example.com:443.
devture_woodpecker_ci_agent_config_server: ''

# This playbook only supports agent-specific secrets, i.e., it is not recommended to use
# a shared secret between Woodpecker CI Server and all of its agents.  Please refer to
# the following upstream documentation in order to learn how to register an agent and
# obtain a secret for it:
#
#   https://woodpecker-ci.org/docs/administration/agent-config#using-agent-token
#
# then, when you have the agent secret, uncomment the following line.
#devture_woodpecker_ci_agent_config_agent_secret: ''

# Uncomment the line below if you want the agent to connect to the
# server over a secure gRPC channel (recommended).
#devture_woodpecker_ci_agent_config_grpc_secure: true

# Uncomment the line below if you want the agent to verify the
# server's TLS certificate when connecting over a secure gRPC channel.
#devture_woodpecker_ci_agent_config_grpc_verify: true

########################################################################
#                                                                      #
# /woodpecker-ci-agent                                                 #
#                                                                      #
########################################################################

Usage

The agent should automatically register with the Woodpecker CI server and take jobs from it.