Skip to main content
In this step-by-step tutorial, you’ll learn how to use Jenkins’ Organization Folder project type with Gitea-hosted repositories. You’ll:
  1. Migrate a GitHub repository to Gitea
  2. Install and configure the Gitea plugin in Jenkins
  3. Create and configure an Organization Folder
  4. Observe automatic multibranch pipeline creation and webhook-triggered builds

​
1. Migrate the Solar System Repository to Gitea

First, copy the clone URL of the Solar System repository from GitHub:
The image shows a GitHub repository page for a project named "solar-system-gitea," displaying files, commit history, and language usage statistics.
Sign in to your Gitea instance:
The image shows a login page for Gitea, with fields for entering a username or email address and a password. There are options to sign in, register, or recover a forgotten password.
Go to your organization (e.g., dasher-org) and click + → New Migration:
The image shows a Gitea dashboard for the "dasher-org" organization, displaying two Java repositories and information about members and teams.
Paste the GitHub URL, set the owner to dasher-org, and name the repo solar-system:
The image shows a Gitea interface for migrating a repository, with options for selecting the owner, repository name, and visibility. There are checkboxes for migration options and items, and a "Migrate Repository" button.
Once migration completes, verify the new repository by visiting its Gitea page:
The image shows a GitHub repository interface for a project named "solar-system" under the organization "dasher-org." It displays details like commits, branches, and files, with a dropdown menu for branch selection.

​
2. Why Use an Organization Folder?

Manually creating a separate Pipeline job for each repository or branch can quickly become a maintenance headache. With the Organization Folder, Jenkins automatically scans your SCM, creates or removes jobs based on your configuration, and keeps everything in sync.
AspectManual PipelinesOrganization Folder
Setup per repoManual each timeSingle configuration
Branch managementManual updatesAutomatic discovery
ScalabilityLimited by manual processesScales with your codebase
Organization Folders streamline multibranch pipeline management and support GitHub, Bitbucket, Gitea, and more.
For further details, see the Jenkins documentation:
The image shows a webpage from the Jenkins documentation, specifically discussing best practices for using organization folders to manage jobs automatically. It includes a sidebar with navigation links and a video thumbnail about creating a GitHub organization in Jenkins.

​
3. Create an Organization Folder in Jenkins

  1. From the Jenkins dashboard, click New Item.
  2. Enter GitHub Organization (or any descriptive name).
  3. Select Organization Folder and click OK:
The image shows a Jenkins interface for creating a new item, with options to select different project types such as Freestyle project, Pipeline, Multi-configuration project, and Folder.

​
4. Install and Configure the Gitea Plugin

​
Install the Plugin

  1. Navigate to Manage Jenkins → Manage Plugins.
  2. In the Available tab, search for Gitea plugin.
  3. Select and install it, checking Restart Jenkins when installation is complete and no jobs are running:
The image shows a Jenkins interface with a search for plugins, displaying a list of available plugins with details like name, version, and release date.
Wait for the installation to finish:
The image shows a Jenkins interface displaying the download progress of plugins, with various components marked as successful and Jenkins currently running.
After Jenkins restarts, verify the plugin is listed under Installed:
The image shows the Jenkins interface displaying a list of installed plugins, with options to search and manage them.

​
Configure Gitea Server

  1. Go to Manage Jenkins → Configure System.
  2. Scroll to Gitea Servers and click Add Gitea Server.
  3. Enter:
    • Name: Gitea server
    • API URL: https://<your-gitea-url>/api/v1
  4. Check Manage hooks to enable automatic webhook creation.
  5. Next to Credentials, click Add, select Username with password, and enter your Gitea credentials (scope: Global):
The image shows a Jenkins configuration screen for setting up a Gitea server, including fields for the server name and URL. There are options to manage hooks and advanced settings, with "Save" and "Apply" buttons at the bottom.
The image shows a Jenkins interface for adding credentials, with fields for domain, kind, scope, username, and password. The browser has multiple tabs open, including GitHub and Gitea.
  1. Click Apply and Save:
The image shows a Jenkins configuration page for setting up a Gitea server, including fields for server name, URL, and credentials. A password manager prompt is visible, offering to save the username and password.

​
5. Configure the Organization Folder

  1. Open the GitHub Organization item and click Configure.
  2. Under Repository Sources, click Add Source → GitHub Organization.
  3. Select:
    • GitHub Server: your configured server
    • Credentials: the admin credential you added
    • Owner: dasher-org
  4. Leave discovery and project recognizer settings at default (looks for Jenkinsfile):
The image shows a Jenkins configuration page with options for setting up a project, including repository sources like Bitbucket and GitHub. The interface includes fields for display name and description, with a sidebar for additional settings.
The image shows a configuration screen for a Jenkins pipeline, specifically setting the script path for a Jenkinsfile. There are options to add project recognizers and set property strategies for branches.
  1. Click Save. Jenkins begins scanning the organization immediately.

​
6. Organization Scan and Job Creation

During the scan, Jenkins inspects each repository and its branches for a Jenkinsfile. Only those that match will have jobs created or updated.
The image shows a Jenkins dashboard with a log of a Gitea organization scan. It includes details about the scan process, such as checking repositories and updating actions.
Example scan output: 
Checking repository parameterized-pipeline-job-init
Proposing parameterized-pipeline-job-init
Looking up repository dasher-org/parameterized-pipeline-job-init

Checking branches...
Checking branch main
'Jenkinsfile' found
Met criteria

1 branches were processed (query completed)

Checking repository solar-system
Proposing solar-system
Looking up repository dasher-org/solar-system

Checking branches...
Checking branch main
'Jenkinsfile' not found
Does not meet criteria

1 branches were processed
Checking pull requests...
0 pull requests were processed

3 repositories were processed
[Mon Sep 23 07:23:10 UTC 2024] Finished organization scan. Scan took 1.8 sec
Finished: SUCCESS
In this example:
  • parameterized-pipeline-job-init → multibranch pipeline created
  • solar-system → skipped (no Jenkinsfile)
The image shows a Jenkins dashboard displaying the status of a pipeline job, with a successful build and test result trend. It includes details like the project name, last successful artifacts, and build history.

​
7. Inspecting Branch Pipelines

Click the parameterized-pipeline-job-init item to view branch-level pipelines:
The image shows a Jenkins dashboard displaying the status of a parameterized pipeline job with branches "main" and "test," both having successful builds.
Repository details such as files and commit history are pulled from Gitea:
The image shows a GitHub repository interface with a list of files and their commit messages. It includes details like the number of commits, branches, and file sizes.

​
8. Webhook Configuration and Automatic Triggers

By enabling Manage hooks, Jenkins automatically adds webhooks to each repository. These webhooks trigger builds on push, branch/tag creation, and pull request events.
The image shows a GitHub settings page for updating a webhook, with options for selecting pull request events and a branch filter. There are buttons for updating or removing the webhook at the bottom.
For example, edit the README in the main branch: 
git checkout main
# edit README.md
git add README.md
git commit -m "Edited README"
git push origin main
The webhook notifies Jenkins, triggering a new build:
The image shows a Jenkins dashboard displaying the status of a pipeline job, with stages like "Checkout SCM," "Build," and "Test" marked as completed. It also includes a test result trend graph and build history.
Ensure your Gitea API token has permissions to create webhooks and read repositories.

​
Conclusion

After adding a Jenkinsfile to the solar-system repository, Jenkins picks it up in the next scan and automatically creates a pipeline:
The image shows a Jenkins dashboard displaying a list of jobs with their statuses, last success, last failure, and duration details.

Watch Video