|
| 1 | +# Create Your Plugin |
| 2 | + |
| 3 | +## Introduction |
| 4 | + |
| 5 | +You can create CI/CD plugins using APIs. It can be any of the following: CI plugin or CD plugin. |
| 6 | + |
| 7 | +Your plugin can be a single-step or multi-step plugin, where steps can be considered as tasks. The task can either be simple shell commands or it can be complex operations that require a specific container environment. |
| 8 | + |
| 9 | +--- |
| 10 | + |
| 11 | +## API Call |
| 12 | + |
| 13 | +{% hint style="warning" %} |
| 14 | +### Prerequisite |
| 15 | +You will need a [token](../../user-guide/global-configurations/authorization/api-tokens.md) to make API calls |
| 16 | +{% endhint %} |
| 17 | + |
| 18 | +``` |
| 19 | +POST {{DEVTRON_BASEURL}}/orchestrator/plugin/global |
| 20 | +``` |
| 21 | + |
| 22 | +--- |
| 23 | + |
| 24 | +## Example Plugin |
| 25 | + |
| 26 | +In the following example, we are creating a single-step plugin named **Secret Management Validator**. Moreover, we want to execute a simple shell script; therefore, we are keeping the task type as `SHELL` |
| 27 | + |
| 28 | +### Sample Request Body |
| 29 | + |
| 30 | +{% code title="Plugin Request Body" overflow="wrap" lineNumbers="true" %} |
| 31 | + |
| 32 | +```json |
| 33 | +{ |
| 34 | + "name": "Secret Management Validator", |
| 35 | + "description": "The Secret Management Validator plugin integrates with your CI/CD pipeline to automatically detect and prevent the inclusion of secrets or sensitive information in your codebase, ensuring compliance and security.", |
| 36 | + "type": "SHARED", |
| 37 | + "icon": "https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/vectors/secret-management-validator.png", |
| 38 | + "tags": ["security", "compliance", "secrets"], |
| 39 | + "action": 0, |
| 40 | + "pluginStage": "CI_CD", |
| 41 | + "pluginSteps": [ |
| 42 | + { |
| 43 | + "name": "Step 1", |
| 44 | + "description": "Step 1 - Secret Management Validator", |
| 45 | + "index": 1, |
| 46 | + "stepType": "INLINE", |
| 47 | + "refPluginId": 0, |
| 48 | + "outputDirectoryPath": null, |
| 49 | + "dependentOnStep": "", |
| 50 | + "pluginStepVariable": [ |
| 51 | + { |
| 52 | + "name": "PathToScan", |
| 53 | + "format": "STRING", |
| 54 | + "description": "The relative path to the directory or file that needs to be scanned for secrets.", |
| 55 | + "isExposed": true, |
| 56 | + "allowEmptyValue": true, |
| 57 | + "defaultValue": "", |
| 58 | + "variableType": "INPUT", |
| 59 | + "valueType": "NEW", |
| 60 | + "variableStepIndex": 1, |
| 61 | + "variableStepIndexInPlugin": 0 |
| 62 | + }, |
| 63 | + { |
| 64 | + "name": "GitGuardianApiKey", |
| 65 | + "format": "STRING", |
| 66 | + "description": "The API key for GitGuardian to authenticate and use the secret detection service.", |
| 67 | + "isExposed": true, |
| 68 | + "allowEmptyValue": false, |
| 69 | + "defaultValue": "", |
| 70 | + "variableType": "INPUT", |
| 71 | + "valueType": "NEW", |
| 72 | + "variableStepIndex": 1, |
| 73 | + "variableStepIndexInPlugin": 0 |
| 74 | + }, |
| 75 | + { |
| 76 | + "name": "ScanScope", |
| 77 | + "format": "STRING", |
| 78 | + "description": "Defines the scope of the scan. It can be set to scan all files, specific file types, or based on patterns.", |
| 79 | + "isExposed": true, |
| 80 | + "allowEmptyValue": true, |
| 81 | + "defaultValue": "all", |
| 82 | + "variableType": "INPUT", |
| 83 | + "valueType": "NEW", |
| 84 | + "variableStepIndex": 1, |
| 85 | + "variableStepIndexInPlugin": 0 |
| 86 | + }, |
| 87 | + { |
| 88 | + "name": "OutputFormat", |
| 89 | + "format": "STRING", |
| 90 | + "description": "The desired format for the output report, such as JSON, HTML, or plaintext.", |
| 91 | + "isExposed": true, |
| 92 | + "allowEmptyValue": true, |
| 93 | + "defaultValue": "JSON", |
| 94 | + "variableType": "INPUT", |
| 95 | + "valueType": "NEW", |
| 96 | + "variableStepIndex": 1, |
| 97 | + "variableStepIndexInPlugin": 0 |
| 98 | + } |
| 99 | + ], |
| 100 | + "pluginPipelineScript": { |
| 101 | + "script": "\n# Run GitGuardian secret detection\nif [ -n \"$GITGUARDIAN_API_KEY\" ]; then\n echo \"Running GitGuardian Secret Detection...\"\n ggshield scan path $SCAN_PATH --api-key $GITGUARDIAN_API_KEY\nelse\n echo \"GitGuardian API key is missing. Skipping secret detection.\"\nfi\n\n# Output the results\nif [ -f ggshield-output.json ]; then\n cat ggshield-output.json\nelse\n echo \"No GitGuardian output found.\"\nfi", |
| 102 | + "storeScriptAt": "", |
| 103 | + "type": "SHELL" |
| 104 | + } |
| 105 | + } |
| 106 | + ] |
| 107 | +} |
| 108 | + |
| 109 | +``` |
| 110 | +{% endcode %} |
| 111 | + |
| 112 | +Required fields to edit in the above sample payload are: |
| 113 | + |
| 114 | +| Key Path | Description | |
| 115 | +| ------------ | ------------------------------------------------------------- | |
| 116 | +| name | Plugin name | |
| 117 | +| description | Plugin description | |
| 118 | +| tags | Array of tags | |
| 119 | +| icon | Plugin icon url | |
| 120 | +| Plugin steps | Array of tasks to execute (Details of fields discussed below) | |
| 121 | + |
| 122 | +Fields of a plugin steps are: |
| 123 | + |
| 124 | +| Key Path | Description | |
| 125 | +| --------------------------- | -------------------------------------------- | |
| 126 | +| name | Step name | |
| 127 | +| description | Description of step | |
| 128 | +| index | Sequence at which the step needs to executed | |
| 129 | +| outputDirectoryPath | Artifact output path | |
| 130 | +| pluginStepVariable | Array of required input / output variables | |
| 131 | +| pluginPipelineScript.script | Stringified bash script | |
| 132 | + |
| 133 | + |
| 134 | +### Result |
| 135 | + |
| 136 | +Your new plugin will appear under **Shared Plugins** depending on which stage you have created it for: pre/post build (`pluginStage = CI`), pre/post deployment (`pluginStage = CD`), or both (`pluginStage = CI_CD`) |
| 137 | + |
| 138 | + |
| 139 | + |
| 140 | +The variables defined in the `pluginStepVariable` array would appear as shown below. |
| 141 | + |
| 142 | + |
| 143 | + |
| 144 | +--- |
| 145 | + |
| 146 | +## Other API calls |
| 147 | + |
| 148 | +To fetch details of a specific plugin by its ID |
| 149 | + |
| 150 | +``` |
| 151 | +GET |
| 152 | +/orchestrator/plugin/global/detail/{pluginId} |
| 153 | +``` |
| 154 | + |
| 155 | +To fetch details of all plugins |
| 156 | + |
| 157 | +``` |
| 158 | +GET |
| 159 | +/orchestrator/plugin/global/detail/all |
| 160 | +``` |
| 161 | + |
| 162 | +To fetch list of all global variables |
| 163 | + |
| 164 | +``` |
| 165 | +GET |
| 166 | +/orchestrator/plugin/global/list/global-variable |
| 167 | +``` |
| 168 | + |
| 169 | +--- |
| 170 | + |
| 171 | +## Field Definitions |
| 172 | + |
| 173 | +Refer the [spec file](https://github.com/devtron-labs/devtron/blob/main/specs/global-plugin.yaml) for detailed definition of each field present in the request/response body of the API. |
0 commit comments