You can use a configuration extension to override the process of fetching the configuration file (e.g. .drone.yml). This can be used to return default or global configurations for projects where none exists, or even generate configurations on-the-fly. For other use cases you should consider using a conversion extension.

Configuration

You can register a configuration extension by providing the following configuration parameters to the Drone server:

• DRONE_YAML_ENDPOINT

  Provides the endpoint used to make http requests to an extension.

• DRONE_YAML_SECRET

  Provides the token used to authenticate http requests to the extension. This token is shared between the server and extension.

How it Works

The server makes an HTTP post to the configuration extension to fetch the configuration file. If the configuration extension returns a 204 status code the system will fallback to the configuration file in the repository.

Request

The configuration extension receives an HTTP request to return a configuration file. The request body includes the Repository and Build details in JSON format.

Request Body definition:

1
2
3
4

class Request {
  repo: Repo;
  build: Build
}

Repository definition:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

class Repository {
    id: int64;
    uid: string;
    user_id: int64;
    namespace: string;
    name: string;
    slug: string;
    scm: string;
    git_http_url: string;
    git_ssh_url: string;
    link: string;
    default_branch: string;
    private: boolean;
    visibility: string;
    active: boolean;
    config: string;
    trusted: boolean;
    protected: boolean;
    ignore_forks: boolean;
    ignore_pulls: boolean;
    cancel_pulls: boolean;
    timeout: int64;
    counter: int64;
    synced: int64;
    created: int64;
    updated: int64;
    version: int64;
}

Build definition:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

class Build {
    id: int64;
    repo_id: int64;
    number: int64;
    parent: int64;
    status: string;
    error: string
    event: string;
    action: string;
    link: string;
    timestamp: int64;
    title: string;
    message: string;
    before: string;
    after: string;
    ref: string;
    source_repo: string;
    source: string;
    target: string;
    author_login: string;
    author_name: string;
    author_email: string;
    author_avatar: string;
    sender: string;
    params: [string][string];
    cron: string;
    deploy_to: string;
    deploy_id: int64;
    started: int64;
    finished: int64;
    created: int64;
    updated: int64;
    version: int64;
}

Response

The configuration extension should respond to the request with a 200 response code and the raw configuration file. If the configuration extension returns a 204 status code the system will fallback to the configuration file in the repository.

Response definition:

1
2
3

class Config {
    data: string;
}

Authorization

The http request is signed per the http signatures draft specification use the shared secret. The receiver should use the signature to verify the authenticity and integrity of the webhook.

Starter Project

If you are interested in creating a configuration extension we recommend using our starter project as a base to jumpstart development.