Woodpecker

Sign in to the AWS Management Console, open the EC2 service and choose Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for Woodpecker CI. Select the SecureAnyCloud listing, choose Select, then choose Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings, select your VPC and subnet. Create or select a security group that opens port 22 from your management network, port 80 for Woodpecker and port 3000 for the bundled Gitea. Leave the root volume at the default size or larger.

Choose Launch instance. First-boot initialisation takes a short time after the instance state becomes Running and the status checks pass. During this time the image rotates secrets and wires the OAuth callback to the instance address.

This command launches an instance from the SecureAnyCloud Woodpecker CI Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing. Replace <key-name> with your EC2 key pair name and <subnet-id> with your subnet ID. Replace <security-group-id> with a security group that opens ports 22, 80 and 3000 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=woodpecker}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name. You can find it in the EC2 console or with aws ec2 describe-instances.

Connect over SSH with your key pair. This image is Ubuntu 24.04, and the SSH login user is ubuntu.

ssh -i <key-name>.pem ubuntu@<public-ip>

The administrator login is unique to your instance. The image generated it on first boot. Read it as root:

sudo cat /root/woodpecker-credentials.txt

The file lists the Woodpecker URL, the bundled Gitea URL, the administrator user (gitadmin) and the generated password. The same administrator signs in to both Gitea and Woodpecker. Store the password somewhere safe.

Over SSH, confirm that the four services are active and that the public ports are listening:

sudo systemctl is-active gitea woodpecker-server woodpecker-agent nginx
sudo ss -tlnp | grep -E ':(80|3000) '

All four services should report active, with nginx listening on port 80 for Woodpecker and port 3000 for Gitea. The Woodpecker health endpoint is open and answers on the loopback through nginx:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/healthz

A 200 or 204 confirms the Woodpecker server is healthy.

The Woodpecker web interface is served on port 80 by nginx. In a browser, go to:

http://<instance-public-ip>/

Choose Login. Woodpecker authenticates through the bundled Gitea, so you are redirected to the Gitea sign-in page on port 3000. Sign in as gitadmin with the password from the credentials file. Then choose Authorize Application on the OAuth consent screen. You return to Woodpecker, signed in.

The OAuth application, its client credentials and the callback URL are all configured for you. You do not need to create anything in Gitea by hand.

Push a repository to the bundled Gitea, or create one in the Gitea web interface on port 3000. Add a .woodpecker.yml file to it. A minimal pipeline looks like this:

when: - event: [push, manual] steps: - name: build image: alpine commands: - echo "Building on Woodpecker CI" - uname -a

In Woodpecker, choose Add repository, then choose Enable next to your repository. Enabling the repository registers a webhook in Gitea, so every push triggers a pipeline. Push a commit, and the Woodpecker agent runs the pipeline in containers using the Docker backend.

The repository, its commits, the .woodpecker.yml pipeline file and the CI status for each commit are all visible in the bundled Gitea on port 3000.

The Woodpecker store and the Gitea database and git repositories live on a dedicated EBS volume mounted at /var/lib/woodpecker. This keeps the application data off the operating system disk and lets you resize or snapshot it independently. Confirm the mount with:

df -h /var/lib/woodpecker

To grow the store, expand the EBS volume in the AWS console. Then grow the filesystem on the instance with sudo resize2fs on the underlying device.

To use your own GitHub, Gitea, Forgejo or GitLab instead of the bundled Gitea, register an OAuth application in your forge and edit the Woodpecker server environment file. The server configuration lives at /etc/woodpecker/server.env:

sudo cat /etc/woodpecker/server.env

Create an OAuth application in your external forge with the authorization callback URL http://<instance-public-ip>/authorize. Then set the forge driver, forge URL and the OAuth client ID and secret in /etc/woodpecker/server.env. For an external Gitea or Forgejo, the keys are WOODPECKER_GITEA=true, WOODPECKER_GITEA_URL, WOODPECKER_GITEA_CLIENT and WOODPECKER_GITEA_SECRET. For GitHub, use the WOODPECKER_GITHUB keys. For GitLab, use the WOODPECKER_GITLAB keys. The Woodpecker documentation describes them. Restart the server to apply the change:

sudo systemctl restart woodpecker-server

If you no longer need the bundled Gitea, stop and disable it with sudo systemctl disable --now gitea. Leave it enabled if you still want a local forge alongside your external one.

nginx serves the Woodpecker and Gitea interfaces over plain HTTP on ports 80 and 3000. For production workloads, place them behind TLS.

Obtain a certificate for your domain. For example, use a managed certificate on an Application Load Balancer in front of the instance, or install Certbot on the instance. Then configure nginx to listen on 443 with your certificate. Proxy to the Woodpecker and Gitea backends exactly as the bundled site does for HTTP.

When you move to HTTPS, update WOODPECKER_HOST and the Gitea ROOT_URL to the https:// URL. Update the OAuth application's callback URL to match. Restrict the security group so the ports are reachable only from the networks that use the service.

Back up the appliance by snapshotting the /var/lib/woodpecker EBS volume. The snapshot captures the Woodpecker store and the Gitea database and git repositories.

Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade, and reboot when a new kernel is installed. All four services start automatically on boot. The image re-wires the OAuth callback and forge URLs to the current public address on each boot.