Gitea
Coolify can deploy Gitea repositories through a public HTTPS URL, an SSH deploy key, or a Gitea App.
| Method | Best for | Repository access |
|---|---|---|
| Public repository | Public source that needs no authentication | HTTPS URL |
| Deploy key | One private repository, or a Gitea instance where an OAuth2 application is unavailable | SSH URL and repository deploy key |
| Gitea App | Private repositories on gitea.com or a self-hosted Gitea instance | OAuth2 application with repository browsing |
Set up a Gitea App
Gitea App integration is available in Coolify v4.5.0 or above.
A Gitea App lets Coolify list repositories and branches, clone private source over HTTPS, and receive push and pull-request events. Gitea has no installable apps like GitHub, so a Gitea App is a Gitea OAuth2 application that you connect to Coolify.
Add the source in Coolify
Open Sources and select New Source > Gitea App.
Enter Name. To limit the repositories that Coolify lists, enter comma-separated organization or user names in Organization. For a self-hosted instance, expand Self-hosted Gitea and enter Gitea URL. Coolify fills in API URL (the Gitea URL with /api/v1). gitea.com is the default.
On a self-hosted Coolify instance, enable System wide only when every team must be able to select this source. Otherwise, keep the source scoped to the active team.
Select Continue. Coolify shows the redirect URI for the OAuth2 application.
Create the OAuth2 application in Gitea
In Gitea, open Settings > Applications and go to Manage OAuth2 Applications. An organization owner can create the application in the organization settings, and an administrator can create it in Site Administration > Applications, when one user must not own it.
Create an application with:
- the exact redirect URI that Coolify shows
- Confidential client selected
Save the application, then copy its Client ID and Client secret.
Connect Coolify to Gitea
Go back to the Gitea source in Coolify. Enter Client ID and Client secret, then select Save.
Select Connect to Gitea. Gitea asks you to authorize the read:user, read:repository, and read:organization scopes. Select Authorize Application.
After Gitea sends you back to Coolify, the source shows Connected. Select Test Connection to make sure that Coolify can call the Gitea API.
Configure webhooks
Copy Webhook URL and Webhook secret from the connected source.
In Gitea, add a webhook of type Gitea. You can add it in the settings of a user, an organization, or one repository. A user or organization webhook sends events for all repositories of that owner. Set:
- Target URL to the Coolify webhook URL
- HTTP Method to
POSTand POST Content Type toapplication/json - Secret to the Coolify webhook secret
- Push events for branch deployments
- Pull Request events for preview deployments
Coolify rejects Gitea webhook requests when the signature is missing or does not match the secret.
Deploy a repository
Open a Coolify project, select + New, then select Git Repository (with Gitea App).
Choose the server and the connected Gitea App. Select a repository, select Load Repository, choose the branch, then configure and deploy the application.
Make sure that the deployment log imports the selected repository and checks out the requested commit.
Self-hosted Gitea network requirements
- Coolify must reach the Gitea URL to exchange OAuth2 codes, refresh tokens, and call the API. The deployment server must reach it to clone repositories.
- Your browser must reach the Gitea URL to authorize the application.
- Gitea must reach the Coolify webhook URL. By default, Gitea blocks webhooks to private networks. If Coolify runs on a private address, add it to
ALLOWED_HOST_LISTin the[webhook]section of the Giteaapp.ini. - Set
ROOT_URLin the Giteaapp.inito the URL that you enter in Coolify.
Gitea OAuth2 access tokens expire after one hour. Coolify refreshes them automatically before each API call and clone.
Use a deploy key
Use a deploy key when Coolify only needs one private repository, or when Coolify cannot connect to the Gitea instance through OAuth2.
- Add a private key under Keys & Tokens > Private Keys.
- Add its public key in the Gitea repository under Settings > Deploy Keys.
- Copy the repository SSH URL, such as
git@gitea.example.com:example/application.git. - In Coolify, create Private Repository (with deploy key) and select the stored key.
Read Deploy keys for the complete setup and security guidance.
Configure a manual Gitea webhook
For an application that you created from a public URL or a deploy key:
- Open Webhooks in the Coolify application.
- Copy the Gitea URL.
- Enter Webhook secret in the Gitea section, then select Save changes.
- In Gitea, open the repository webhook settings.
- Enter the URL and the same secret.
- Enable Push.
- Enable pull-request events when you use preview deployments.
- Open Advanced > Deployment and choose Deploy on push (webhooks) in Auto deploy in Coolify.
Test a push deployment first. Then open or update a pull request and examine Preview Deployments.