Drone CI can automatically build your code whenever you push changes, but it won’t do that for every repository you have. You need to explicitly tell Drone which repositories to watch.
Let’s see it in action. Imagine you have a GitHub repository named my-org/my-app. To get Drone to watch this repository for new commits, you’d typically go to your Drone dashboard (e.g., https://drone.example.com) and click a button to "Activate" or "Sync" repositories. If you’re using GitHub, Drone will ask for permission to access your repositories. Once authorized, you’ll see a list of your repositories, and you can toggle the switch next to my-org/my-app to activate it.
Here’s what happens under the hood when you activate a repository:
- Webhook Registration: Drone registers a webhook with your Git provider (GitHub, GitLab, Bitbucket, etc.). This webhook tells your Git provider to send an HTTP POST request to a specific Drone endpoint whenever a
pushevent occurs on your activated repository. The payload of this request contains details about the commit, branch, author, and other relevant information. - Repository Synchronization: Drone also synchronizes its internal database with your Git provider. This ensures Drone knows about the repository, its branches, and its default branch. This synchronization is crucial for Drone to correctly interpret incoming webhook events.
- Permissions and Scopes: When you authorize Drone, you grant it specific permissions (scopes) on your Git provider. For GitHub, this typically includes
reposcope, which allows Drone to read repository metadata, register webhooks, and clone the repository for building.
The problem this solves is simple: you have many repositories, but you only want to build a subset of them. Activating a repository tells Drone, "Hey, pay attention to this one, and let me know when code changes." Without activation, Drone is essentially deaf to any activity in that repository.
The exact levers you control are primarily through the Drone UI and the permissions you grant it on your Git provider. You can:
- Activate/Deactivate: Turn build monitoring on and off for individual repositories.
- Configure Permissions: Control what Drone can see and do by managing the OAuth scopes granted to the Drone application on your Git provider.
- Specify Branches (indirectly): While activation is repository-wide, your
.drone.ymlpipeline configuration dictates which branches trigger builds or have specific pipeline steps executed.
When you activate a repository, Drone creates an entry in its database that maps the repository’s unique identifier (e.g., github.com/my-org/my-app) to its internal representation. This entry stores the webhook URL provided by your Git provider and any necessary authentication tokens. It also links the repository to your user account within Drone, ensuring you have the necessary permissions to manage its build settings.
Most people don’t realize that the webhook Drone registers is usually specific to the repository and the Drone instance. It’s not a generic endpoint. When GitHub sends a push event, it includes the repository name in the payload, and Drone uses this to look up the correct internal configuration for that repository and trigger the associated pipeline. If this webhook is misconfigured or deleted (sometimes by Git provider housekeeping or manual intervention), Drone will stop receiving events.
The next concept you’ll likely run into is defining your build pipelines using the .drone.yml file.