Improving Renovate for Self-Hosted Gitea: Automatic Dependency Updates Across All Repositories
Nov 17, 2026
Self-hosted dependency management with Gitea Actions, centralized configuration, and automatic repository discovery.
I recently came across an article by Vladi Iancu explaining how to configure Renovate on a self-hosted Gitea or Forgejo instance.
I’d been looking for something similar to GitHub’s Dependabot for my own Gitea server, and Renovate seemed like a good solution.
Vladi’s tutorial does a great job explaining the basics. It walks through creating a dedicated bot account, setting up a configuration repository, and scheduling Renovate using Gitea Actions.
I followed the tutorial and got Renovate working, but there were a few things I wanted to improve.
In particular, I didn’t want to create a renovate.json file in every repository, and I wanted Renovate to automatically discover new repositories without any additional configuration.
I also wanted to be able to trigger Renovate manually, manage dependencies across repositories with different default branches, and review updates before merging them.
Here’s what I ended up with.
Prerequisites#
Before getting started, you’ll need:
- A self-hosted Gitea or Forgejo instance.
- Gitea Actions enabled with at least one working runner.
- Administrator access to your Gitea instance.
- A GitHub personal access token for dependency metadata.
This tutorial assumes Gitea, although the general approach works with Forgejo as well. Check the appropriate Renovate platform documentation if your Forgejo version requires different settings.
1. Create a dedicated Renovate user#
First, log into Gitea as an administrator and navigate to:
Site Administration → Identity & Access → User Accounts
Create a new user named renovate-bot.
Using a dedicated account makes it easier to identify dependency updates and manage permissions independently from your personal account.
Log into Gitea as the new user and navigate to:
Settings → Applications → Generate New Token
Create a personal access token with the following permissions:
| Permission | Access |
|---|---|
| Repository | Read and Write |
| Issue | Read and Write |
| User | Read |
| Organization | Read |
| Package | Read, if needed |
One important detail is the read:user permission.
During my initial setup, Renovate successfully connected to the Gitea API but failed with a 403 Forbidden response because the token didn’t have that permission.
The logs made the problem fairly obvious:
required=[read:user]
token scope=write:repository,write:issue,...After generating a new token with the required permissions, Renovate authenticated successfully.
Save the token somewhere secure. We’ll need it shortly.
2. Create a centralized configuration repository#
Back in your regular Gitea account, create a repository named:
renovate-configThis repository will contain two files:
renovate-config/
├── config.js
└── .gitea/
└── workflows/
└── renovate.ymlThe config.js file defines how Renovate operates, while the workflow schedules and executes Renovate using Gitea Actions.
This is essentially the same approach Vladi used in his original tutorial.
The main difference is how we’ll configure repository discovery and onboarding.
3. Configure Renovate to manage repositories automatically#
In renovate-config, create config.js:
module.exports = {
platform: "gitea",
endpoint: "https://git.example.com/api/v1",
gitAuthor: "Renovate Bot <[email protected]>",
// Automatically discover accessible repositories
autodiscover: true,
// No renovate.json required in each repository
requireConfig: "optional",
onboarding: false,
// Default dependency update configuration
extends: ["config:recommended"],
// Require manual merging
automerge: false,
// Enable the Dependency Dashboard
dependencyDashboard: true,
// Limit the number of open PRs
prConcurrentLimit: 10,
prHourlyLimit: 5,
timezone: "America/Detroit",
};Replace git.example.com and the email address with your own values.
There are a few important differences from the original tutorial.
Automatic repository discovery#
The first is:
autodiscover: true;This tells Renovate to discover repositories accessible to the bot account.
Instead of maintaining a list of repository names, Renovate discovers eligible repositories automatically during each run.
This is particularly useful when you’re regularly creating new projects.
However, autodiscovery only works for repositories the bot has permission to access. We’ll address that shortly.
No more renovate.json in every repository#
This is probably my favorite improvement:
requireConfig: "optional",
onboarding: false,In the original tutorial, each repository needs its own renovate.json file, and Renovate creates an onboarding pull request to enable dependency updates.
There’s nothing wrong with that approach, especially if you want to explicitly approve Renovate for each repository.
But I wanted dependency management to work automatically.
With these two settings, Renovate processes accessible repositories even when they don’t contain a renovate.json file.
The centrally defined configuration becomes the default.
Individual repositories can still provide their own configuration if they need something different.
For example, one project might need to ignore a particular dependency:
{
"extends": ["config:recommended"],
"ignoreDeps": ["some-package"]
}That allows repository-specific customization without requiring configuration files everywhere.
What happened to optimizeForDisabled?#
Vladi’s original configuration includes:
optimizeForDisabled: true;I initially kept this option as well, but eventually removed it.
According to Renovate’s documentation, this setting performs an additional check to determine whether a repository explicitly contains "enabled": false before cloning it.
It can be useful for installations where many repositories have deliberately disabled Renovate.
For my setup, where the goal is to automatically manage most repositories, it wasn’t necessary.
4. Create the Gitea Actions workflow#
Next, create:
.gitea/workflows/renovate.ymlHere’s the workflow:
name: renovate
on:
workflow_dispatch:
schedule:
- cron: "0 3 * * *"
push:
branches:
- main
jobs:
renovate:
runs-on: ubuntu-latest
container:
image: ghcr.io/renovatebot/renovate:44.236.4
steps:
- name: Checkout configuration
uses: actions/checkout@v4
- name: Run Renovate
run: renovate
env:
RENOVATE_CONFIG_FILE: config.js
LOG_LEVEL: debug
RENOVATE_TOKEN: ${{ secrets.RENOVATE_TOKEN }}
RENOVATE_GITHUB_COM_TOKEN: ${{ secrets.TOKEN_GITHUB }}This is the core workflow. It assumes your runner can already execute container jobs and access your Gitea instance.
I’ve used Renovate 44.236.4, the version I tested successfully. You should check for a newer supported release before deploying this yourself.
There are three changes worth explaining.
Manual workflow execution#
The first is:
workflow_dispatch:This allows you to execute Renovate manually from the Gitea Actions interface.
The original tutorial uses scheduled and push events, but I found manually triggering the workflow especially useful while experimenting with configuration changes.
After making a change to config.js, I can immediately run Renovate and inspect the results.
Scheduling Renovate#
The workflow includes:
schedule:
- cron: "0 3 * * *"This executes Renovate daily at 03:00 UTC.
You can run it more frequently if needed, although daily checks are generally sufficient for my projects.
The workflow also runs when changes are pushed to the main branch of renovate-config.
Make sure the branch name matches your configuration repository’s actual default branch.
Simpler configuration file location#
Instead of specifying an absolute path such as:
/workspace/username/renovate-config/config.jsI’m using:
RENOVATE_CONFIG_FILE: config.jsSince the workflow checks out the configuration repository into its working directory, the relative path is sufficient.
This also avoids depending on a particular directory structure inside the runner.
5. Add your Gitea Actions secrets#
In the renovate-config repository, navigate to:
Settings → Actions → Secrets
Create the following secrets:
| Name | Value |
|---|---|
RENOVATE_TOKEN | Personal access token belonging to renovate-bot |
TOKEN_GITHUB | GitHub personal access token |
The Gitea token allows Renovate to discover repositories, push branches, and create pull requests.
The GitHub token allows Renovate to access GitHub’s API for dependency metadata, release information, and changelogs without relying on unauthenticated rate limits.
Make sure the tokens have only the permissions they need.
6. Grant renovate-bot access to your repositories#
This is an important part of the setup.
Enabling autodiscovery doesn’t automatically give Renovate permission to manage every repository in Gitea.
The bot still needs the appropriate repository permissions.
For repositories under a personal account, you can add renovate-bot as a collaborator with write access.
But if you have many repositories, there’s a better way.
Using Gitea organizations#
Gitea supports organization teams that can be granted access to all repositories within an organization.
You can create a team named something like:
dependency-botsGive the team access to all organization repositories, including newly created ones, and add renovate-bot as a member.
Now you don’t need to invite the bot individually every time you create another organization repository.
Combined with autodiscover: true, this makes the process almost completely automatic.
Create a repository, push your code, and Renovate can discover it on its next scheduled run.
For personal repositories, individual collaborator permissions may still be necessary.
7. Run Renovate#
At this point, we should have everything needed.
Open:
renovate-config → Actions → renovate
Select the option to run the workflow manually.
If everything is configured correctly, Renovate should start examining the repositories accessible to its bot account.
With debug logging enabled, you’ll see messages describing repository discovery, dependency extraction, version lookups, and pull request creation.
For example:
INFO: Renovate started
DEBUG: Parsing configs
DEBUG: File config
DEBUG: Combined config
DEBUG: Using queue: host=git.example.comOne thing to remember is that a successful workflow doesn’t necessarily mean Renovate created any PRs.
It might have discovered no repositories, found no available updates, or reached a configured pull request limit.
Inspect the logs to see exactly which repositories were processed.
When updates are available and permitted by your configuration, Renovate will create branches and open pull requests.
Because we configured automerge: false, those PRs remain available for manual review rather than being merged automatically.
8. Supporting main, master, and production branches#
Another thing I wanted was support for repositories using different default branch names.
Some of my repositories use main, while others still use master.
Fortunately, Renovate handles this automatically.
By default, Renovate targets each repository’s default branch, regardless of its name.
That means you don’t need to list both main and master in baseBranchPatterns just to support different repositories.
But what if a repository has both main and prod, and you want dependency update PRs targeting both branches?
You can configure:
baseBranchPatterns: [
"$default",
"prod"
],$default represents the repository’s default branch, while prod adds another branch when it exists.
This is useful for projects that maintain multiple independent release streams.
However, there is something worth knowing before changing this setting on an existing Renovate installation.
Be careful when changing branch patterns#
I ran into an interesting issue while experimenting with multiple base branches.
Renovate initially created dependency branches with names similar to:
renovate/master-github.com-charmbracelet-keygen-0.xAfter changing the branch configuration, Renovate started expecting:
renovate/github.com-charmbracelet-keygen-0.xThe difference seems small, but Renovate uses branch names to identify and track dependency updates.
When the naming convention changed, Renovate considered the previous branches stale.
It automatically closed their PRs and removed the branches.
This was confusing at first because the PRs were closed without being merged, and the dependency files in master remained unchanged.
The logs showed:
DEBUG: Found PR #166
DEBUG: branch.isModified() = false
INFO: Autoclosing PR
DEBUG: Deleted remote branchThe branch.isModified() = false message doesn’t mean there are no differences between the update branch and its target branch. It means Renovate detected no user modifications that would prevent its normal branch cleanup.
The important lesson is to choose your branch strategy early and avoid changing it unnecessarily.
For most installations, I would simply let Renovate update each repository’s default branch.
Only configure additional base branches if you actually need independent dependency updates across multiple branches.
9. Configure pull request limits#
Another thing I discovered while debugging the closed PRs was Renovate’s default hourly pull request limit.
My logs included:
DEBUG: Hourly PRs limit reached
"hourlyPrCount": 2,
"hourlyPrLimit": 2
DEBUG: Reached branch limit - skipping branch creationBy default, Renovate limits how many PRs it creates in a given hour.
This is useful because a repository with many outdated dependencies could otherwise generate a large number of PRs immediately.
For my installation, I increased the limits slightly:
prHourlyLimit: 5,
prConcurrentLimit: 10,This allows up to five new PRs per hour and ten open Renovate PRs per repository.
The limits don’t force Renovate to create that many PRs. They simply control how quickly updates can be introduced.
If you’re managing repositories with significant CI workloads, you might prefer lower limits.
10. Should Renovate automatically merge updates?#
Vladi’s original tutorial includes a configuration that automatically merges selected dependency updates.
That’s a useful feature, especially for small patch releases, but I decided to start with:
automerge: false,For now, I’d rather review dependency updates and verify that my existing Gitea Actions tests pass before merging.
Later, it’s possible to enable automerging selectively.
For example:
packageRules: [
{
matchUpdateTypes: ["patch"],
automerge: true,
},
];This would permit Renovate to automatically merge patch updates, subject to the repository’s applicable checks and merge requirements.
I wouldn’t recommend enabling this until your CI pipelines are reliable.
Also, automerging doesn’t prevent Renovate from closing obsolete PRs. That’s a separate part of Renovate’s branch management.
11. Extending Renovate with notifications#
One additional improvement worth considering is integrating Renovate with a notification service such as ntfy.
Gitea supports system-level webhooks, allowing events to be delivered from repositories across an instance.
That makes it possible to receive notifications when dependency PRs are opened, updated, or merged.
You can also use Gitea Actions to send notifications when a Renovate workflow fails or generate a daily summary of outstanding dependency updates.
I prefer this approach over continuously checking the Gitea interface for new PRs.
The notification integration is an optional extension, rather than a requirement for Renovate itself. Direct webhook notifications also need additional filtering if you only want alerts for PRs created by renovate-bot.
Final thoughts#
Vladi’s original tutorial gave me a straightforward starting point for setting up Renovate on my self-hosted Gitea instance.
The basic architecture remains the same: a dedicated bot account, a centralized configuration repository, and a scheduled workflow executed through Gitea Actions.
The biggest improvements I made were removing the need for configuration files in every repository, enabling automatic discovery, and centralizing dependency update policies.
The result is an installation where I can create a new repository, grant Renovate access, and let the next scheduled workflow take care of discovering dependencies and proposing updates.
I also learned a few things along the way, particularly around Gitea token permissions, pull request limits, and how changes to Renovate’s branch configuration can affect existing PRs.
For anyone starting from scratch, I’d recommend getting the simplest setup working first, keeping automerging disabled, and then adding more advanced configuration once you understand how Renovate behaves.
If you’re looking for a good introduction, read Vladi Iancu’s original tutorial. This post is intended as a follow-up for anyone who wants to go a little further and manage dependency updates across an entire self-hosted Gitea installation.
For additional configuration options, the official Renovate documentation is an excellent reference.