Please configure Global Configurations before moving ahead with App Configuration

Parts of Documentation

Git Repository

Build Configuration

Base Deployment Template

GitOps Configuration

Workflow Editor

ConfigMaps

Secrets

External Links

Protect Configuration

Environment Overrides

Deleting Application

Introduction

During the , the application source code is pulled from your .

Devtron also supports multiple Git repositories (be it from one Git account or multiple Git accounts) in a single deployment.

Therefore, this doc is divided into 2 sections, read the one that caters to your application:

Single Repo Application

Follow the below steps if the source code of your application is hosted on a single Git repository.

In your application, go to App Configuration → Git Repository. You will get the following fields and options:

3. (Checkboxes)

Git Account

Git Repo URL

In this field, you have to provide your code repository’s URL, for e.g., https://github.com/devtron-labs/django-repo.

You can find this URL by clicking on the Code button available on your repository page as shown below:

Exclude specific file/folder in this repo

Devtron allows you to create either an exclusion rule, an inclusion rule, or a combination of both. In case of multiple files or folders, you can list them in new lines.

To exclude a path, use ! as the prefix, e.g. !path/to/file To include a path, don't use any prefix, e.g. path/to/file

Examples

You may use the Learn how link (as shown below) to understand the syntax of defining an exclusion or inclusion rule.

Since file paths can be long, Devtron supports regex too for writing the paths. To understand it better, you may click the How to use link as shown below.

How to view excluded commits?

As we saw earlier in fig. 4 and 5, commits containing the changes of only README.md file were not displayed, since the file was in the exclusion list.

However, Devtron gives you the option to view the excluded commits too. There's a döner menu at the top-right (beside the Search by commit hash search bar).

The EXCLUDED label (in red) indicates that the commits contain changes made only to the excluded file, and hence they are unavailable for build.

Set clone directory

After clicking the checkbox, a field titled clone directory path appears. It is the directory where your code will be cloned for the repository you specified in the previous step.

This field is optional for a single Git repository application and you can leave the path as default. Devtron assigns a directory by itself when the field is left blank. The default value of this field is ./

Pull submodules recursively

Multi Repo Application

Repeat the process for every new git repository you add. The clone directory path is used by Devtron to assign a directory to each of your Git repositories. Devtron will clone your code at those locations and those paths can be referenced in the Docker file to create a Docker image of the application.

Whenever a change is pushed to any of the configured repositories, CI will be triggered and a new Docker image file will be built (based on the latest commits of the configured repositories). Next, the image will be pushed to the container registry you configured in Devtron.

Why do you need Multi-Git support?

Let’s look at this with an example:

Due to security reasons, you want to keep sensitive configurations like third-party API keys in separate access-restricted git repositories, and the source code in a Git repository that every developer has access to. To deploy this application, code from both the repositories are required. A Multi-Git support helps you achieve it.

Other examples where you might need Multi-Git support:

• To make code modularized, where front-end and back-end code are in different repos

• Common library extracted out in a different repo so that other projects can use it

This chart deploys Job & CronJob. A Job is a controller object that represents a finite task and CronJob is used to schedule the creation of Jobs.

1. Job

A Job creates one or more Pods and will continue to retry execution of the Pods until a specified number of them successfully terminate. As pods successfully complete, the Job tracks the successful completions. When a specified number of successful completions is reached, the task (ie, Job) is complete. Deleting a Job will clean up the Pods it created. Suspeding a Job will delete its active Pods until the Job is resumed again.

Example:

2. CronJob

A CronJob creates jobs on a repeating schedule. One Cronjob object is like one line of a crontab (cron table) file. It runs a job periodically on a given schedule, written in Cron format. CronJobs are meant for performing regular scheduled actions such as backups, report generation, and so on. Each task must be configured to recur indefinitely (as an example: once a day / week / month). You can schedule the time within that interval when the job should start.

Example:

In this section, we will provide information on the Build Configuration.

Build configuration is used to create and push docker images in the container registry of your application. You will provide all the docker related information to build and push docker images on the Build Configuration page.

Only one docker image can be created for multi-git repository applications as explained in the section.

For build configuration, you must provide information in the sections as given below:

Store Container Image

The following fields are provided on the Store Container Image section:

If you are using docker hub account, you need to enter the repository name along with your username. For example - If my username is kartik579 and repo name is devtron-trial, then enter kartik579/devtron-trial instead of only devtron-trial.

Build the Container Image

In order to deploy the application, we must build the container images to configure a fully operational container environment.

You can choose one of the following options to build your container image:

• I have a Dockerfile

• Create Dockerfile

• Build without Dockerfile

Build Docker Image when you have a Dockerfile

A Dockerfile is a text document that contains all the commands which you can call on the command line to build an image.

Build Docker Image by creating Dockerfile

With the option Create Dockerfile, you can create a Dockerfile from the available templates. You can edit any selected Dockerfile template as per your build configuration requirements.

Build Docker Image without Dockerfile

With the option Build without Dockerfile, you can use Buildpacks to automatically build the image for your preferred language and framework.

Build Env Arguments

You can add Key/Value pair by clicking Add argument.

Advanced Options

Set Target Platform for the build

Using this option, you can build images for a specific or multiple architectures and operating systems (target platforms). You can select the target platform from the drop-down list or can type to select a customized target platform.

Before selecting a customized target platform, please ensure that the architecture and the operating system are supported by the registry type you are using, otherwise build will fail. Devtron uses BuildX to build images for multiple target Platforms, which requires higher CI worker resources. To allocate more resources, you can increase value of the following parameters in the devtron-cm configmap in devtroncd namespace.

• LIMIT_CI_CPU

• REQ_CI_CPU

• REQ_CI_MEM

• LIMIT_CI_MEM

To edit the devtron-cm configmap in devtroncd namespace:

If target platform is not set, Devtron will build image for architecture and operating system of the k8s node on which CI is running.

The Target Platform feature might not work in minikube & microk8s clusters as of now.

Docker Build Arguments

It is is a collapsed view including the following parameters:

• Key

• Value

Click Save Configuration.

Workflow is a logical sequence of different stages used for continuous integration and continuous deployment of an application.

Click on New Build Pipeline to create a new workflow

On clicking New Build Pipeline, three options appear as mentioned below:

• Continuous Integration: Choose this option if you want Devtron to build the image of source code.

• Linked CI Pipeline: Choose this option if you want to use an image created by an existing CI pipeline in Devtron.

• Incoming Webhook: Choose this if you want to build your image outside Devtron, it will receive a docker image from an external source via the incoming webhook.

Then, create CI/CD Pipelines for your application.

The StatefulSet chart in Devtron allows you to deploy and manage stateful applications. StatefulSet is a Kubernetes resource that provides guarantees about the ordering and uniqueness of Pods during deployment and scaling.

It supports only ONDELETE and ROLLINGUPDATE deployment strategy.

You can select StatefulSet chart when you want to use only basic use cases which contain the following:

• Managing Stateful Applications: StatefulSets are ideal for managing stateful applications, such as databases or distributed systems, that require stable network identities and persistent storage for each Pod.

• Ordered Pod Management: StatefulSets ensure ordered and predictable management of Pods by providing each Pod with a unique and stable hostname based on a defined naming convention and ordinal index.

• Updating and Scaling Stateful Applications: StatefulSets support updating and scaling stateful applications by creating new versions of the StatefulSet and performing rolling updates or scaling operations in a controlled manner, ensuring minimal disruption to the application.

• Persistent Storage: StatefulSets have built-in mechanisms for handling persistent volumes, allowing each Pod to have its own unique volume claim and storage. This ensures data persistence even when Pods are rescheduled or restarted.

• Maintaining Pod Identity: StatefulSets guarantee consistent identity for each Pod throughout its lifecycle. This stability is maintained even if the Pods are rescheduled, allowing applications to rely on stable network identities.

• Rollback Capability: StatefulSets provide the ability to rollback to a previous version in case the current state of the application is unstable or encounters issues, ensuring a known working state for the application.

• Status Monitoring: StatefulSets offer status information that can be used to monitor the deployment, including the current version, number of replicas, and the readiness of each Pod. This helps in tracking the health and progress of the StatefulSet deployment.

• Resource Cleanup: StatefulSets allow for easy cleanup of older versions by deleting StatefulSets and their associated Pods and persistent volumes that are no longer needed, ensuring efficient resource utilization.

1. Yaml File

Container Ports

This defines ports on which application services will be exposed to other services

EnvVariables

EnvVariablesFromSecretKeys

It is used to get the name of Environment Variable name, Secret name and the Key name from which we are using the value in that corresponding Environment Variable.

EnvVariablesFromConfigMapKeys

It is used to get the name of Environment Variable name, Config Map name and the Key name from which we are using the value in that corresponding Environment Variable.

To set environment variables for the containers that run in the Pod.

StatefulSetConfig

These are all the configuration settings for the StatefulSet.

Mandatoryfields in statefulSetConfig is

Here is an explanation of each field in the statefulSetConfig :

volumeClaimTemplates: An array of volume claim templates that are used to create persistent volumes for the StatefulSet. Each volume claim template specifies the storage class, access mode, storage size, and other details of the persistent volume.

Liveness Probe

If this check fails, kubernetes restarts the pod. This should return error code in case of non-recoverable error.

MaxUnavailable

The maximum number of pods that can be unavailable during the update process. The value of "MaxUnavailable: " can be an absolute number or percentage of the replicas count. The default value of "MaxUnavailable: " is 25%.

MaxSurge

The maximum number of pods that can be created over the desired number of pods. For "MaxSurge: " also, the value can be an absolute number or percentage of the replicas count. The default value of "MaxSurge: " is 25%.

Min Ready Seconds

This specifies the minimum number of seconds for which a newly created Pod should be ready without any of its containers crashing, for it to be considered available. This defaults to 0 (the Pod will be considered available as soon as it is ready).

Readiness Probe

If this check fails, kubernetes stops sending traffic to the application. This should return error code in case of errors which can be recovered from if traffic is stopped.

Ambassador Mappings

You can create ambassador mappings to access your applications from outside the cluster. At its core a Mapping resource maps a resource to a service.

Autoscaling

This is connected to HPA and controls scaling up and down in response to request load.

Fullname Override

fullnameOverride replaces the release fullname created by default by devtron, which is used to construct Kubernetes object names. By default, devtron uses {app-name}-{environment-name} as release fullname.

Image

Image is used to access images in kubernetes, pullpolicy is used to define the instances calling the image, here the image is pulled when the image is not present,it can also be set as "Always".

imagePullSecrets

imagePullSecrets contains the docker credentials that are used for accessing a registry.

Ingress

This allows public access to the url, please ensure you are using right nginx annotation for nginx class, its default value is nginx

Legacy deployment-template ingress format

Ingress Internal

This allows private access to the url, please ensure you are using right nginx annotation for nginx class, its default value is nginx

Init Containers

Specialized containers that run before app containers in a Pod. Init containers can contain utilities or setup scripts not present in an app image. One can use base image inside initContainer by setting the reuseContainerImage flag to true.

Istio

Istio is a service mesh which simplifies observability, traffic management, security and much more with it's virtual services and gateways.

Pause For Seconds Before Switch Active

To wait for given period of time before switch active the container.

Resources

These define minimum and maximum RAM and CPU available to the application.

Resources are required to set CPU and memory usage.

Limits

Limits make sure a container never goes above a certain value. The container is only allowed to go up to the limit, and then it is restricted.

Requests

Requests are what the container is guaranteed to get.

Service

This defines annotations and the type of service, optionally can define name also.

Volumes

It is required when some values need to be read from or written to an external disk.

Volume Mounts

It is used to provide mounts to the volume.

Affinity and anti-affinity

Spec is used to define the desire state of the given container.

Node Affinity allows you to constrain which nodes your pod is eligible to schedule on, based on labels of the node.

Inter-pod affinity allow you to constrain which nodes your pod is eligible to be scheduled based on labels on pods.

Key

Key part of the label for node selection, this should be same as that on node. Please confirm with devops team.

Values

Value part of the label for node selection, this should be same as that on node. Please confirm with devops team.

Tolerations

Taints are the opposite, they allow a node to repel a set of pods.

A given pod can access the given node and avoid the given taint only if the given pod satisfies a given taint.

Taints and tolerations are a mechanism which work together that allows you to ensure that pods are not placed on inappropriate nodes. Taints are added to nodes, while tolerations are defined in the pod specification. When you taint a node, it will repel all the pods except those that have a toleration for that taint. A node can have one or many taints associated with it.

Arguments

This is used to give arguments to command.

Command

It contains the commands for the server.

Containers

Containers section can be used to run side-car containers along with your main container within same pod. Containers running within same pod can share volumes and IP Address and can address each other @localhost. We can use base image inside container by setting the reuseContainerImage flag to true.

Prometheus

It is a kubernetes monitoring tool and the name of the file to be monitored as monitoring in the given case.It describes the state of the prometheus.

rawYaml

Accepts an array of Kubernetes objects. You can specify any kubernetes yaml here and it will be applied when your app gets deployed.

Grace Period

Kubernetes waits for the specified time called the termination grace period before terminating the pods. By default, this is 30 seconds. If your pod usually takes longer than 30 seconds to shut down gracefully, make sure you increase the GracePeriod.

A Graceful termination in practice means that your application needs to handle the SIGTERM message and begin shutting down when it receives it. This means saving all data that needs to be saved, closing down network connections, finishing any work that is left, and other similar tasks.

There are many reasons why Kubernetes might terminate a perfectly healthy container. If you update your deployment with a rolling update, Kubernetes slowly terminates old pods while spinning up new ones. If you drain a node, Kubernetes terminates all pods on that node. If a node runs out of resources, Kubernetes terminates pods to free those resources. It’s important that your application handle termination gracefully so that there is minimal impact on the end user and the time-to-recovery is as fast as possible.

Server

It is used for providing server configurations.

Deployment

It gives the details for deployment.

Service Monitor

It gives the set of targets to be monitored.

Db Migration Config

It is used to configure database migration.

KEDA Autoscaling

Example for autosccaling with KEDA using Prometheus metrics is given below:

Example for autosccaling with KEDA based on kafka is given below :

Winter-Soldier

Winter Soldier can be used to

• cleans up (delete) Kubernetes resources

• reduce workload pods to 0

Given below is template values you can give in winter-soldier:

Here,

here is an example,

Above settings will take action on Sat and Sun from 00:00 to 23:59:59, and on Mon-Fri from 00:00 to 08:00 and 20:00 to 23:59:59. If action:sleep then runs hibernate at timeFrom and unhibernate at timeTo. If action: delete then it will delete workloads at timeFrom and timeTo. Here the action:scale thus it scale the number of resource replicas to targetReplicas: [1,1,1]. Here each element of targetReplicas array is mapped with the corresponding elements of array timeRangesWithZone/timeRanges. Thus make sure the length of both array is equal, otherwise the cnages cannot be observed.

The above example will select the application objects which have been created 10 hours ago across all namespaces excluding application's namespace. Winter soldier exposes following functions to handle time, cpu and memory.

• ParseTime - This function can be used to parse time. For eg to parse creationTimestamp use ParseTime({{metadata.creationTimestamp}}, '2006-01-02T15:04:05Z')

• AddTime - This can be used to add time. For eg AddTime(ParseTime({{metadata.creationTimestamp}}, '2006-01-02T15:04:05Z'), '-10h') ll add 10h to the time. Use d for day, h for hour, m for minutes and s for seconds. Use negative number to get earlier time.

• Now - This can be used to get current time.

• CpuToNumber - This can be used to compare CPU. For eg any({{spec.containers.#.resources.requests}}, { MemoryToNumber(.memory) < MemoryToNumber('60Mi')}) will check if any resource.requests is less than 60Mi.

Security Context

A security context defines privilege and access control settings for a Pod or Container.

To add a security context for main container:

To add a security context on pod level:

Topology Spread Constraints

You can use topology spread constraints to control how Pods are spread across your cluster among failure-domains such as regions, zones, nodes, and other user-defined topology domains. This can help to achieve high availability as well as efficient resource utilization.

Deployment Metrics

It gives the realtime metrics of the deployed applications

2. Show application metrics

If you want to see application metrics like different HTTP status codes metrics, application throughput, latency, response time. Enable the Application metrics from below the deployment template Save button. After enabling it, you should be able to see all metrics on App detail page. By default it remains disabled.

Helm Chart Json Schema

Other Validations in Json Schema

The values of CPU and Memory in limits must be greater than or equal to in requests respectively. Similarly, In case of envoyproxy, the values of limits are greater than or equal to requests as mentioned below.

A deployment configuration is a manifest of the application. It defines the runtime behavior of the application. You can select one of the default deployment charts or custom deployment charts which are created by super admin.

To configure a deployment chart for your application, do the following steps:

• Go to Applications and create a new application.

• Go to App Configuration page and configure your application.

• On the Base Deployment Template page, select the drop-down under Chart type.

Selecting a Chart Type

From Devtron Charts

You can select a default deployment chart from the following options:

From Deployment Charts

You can select an available custom chart as shown below. You can also view the description of the custom charts in the list.

Selecting a Chart Version

Once you select a chart type, choose a chart version using which you wish to deploy the application.

Devtron uses helm charts for deployments and it maintains multiple chart versions based on the features it supports.

One can see available chart versions in the drop-down. You can select any chart version as per your requirements. By default, the latest version of the helm chart is selected.

Every chart version has its own YAML file that provides specifications for your application. To make it easy to use, we have created templates for the YAML file and have added some variables inside the YAML. You can provide or change the values of these variables as per your requirement.

Configuring the Chart

Using Basic GUI

If you are not an advanced user, you may use the Basic (GUI) section to configure your chosen chart.

By default, the following fields are available for you to modify in the Basic (GUI) section:

Click Save Changes. If you want to do additional configurations, then click the Switch to Advanced button or Advanced (YAML) button for modifications.

This is useful in scenarios where:

• You frequently edit certain fields in Advanced (YAML), which you expect to remain easily accessible in Basic (GUI) section.

• You don't require some fields in Basic (GUI) section.

• You need the autonomy to keep the Basic (GUI) unique for applications/clusters/environments/charts, or display the same Basic (GUI) everywhere.

You can pass a custom JSON (deployment schema) of your choice through the following API. You may need to run the API with the POST method if you are doing it for the first time.

1. In the name field, give a name to your schema, e.g., schema-1

2. Enter the type as JSON.

3. The schema field is for entering your custom deployment schema. Perform the following steps:

   • Copy the final JSON and stringify it using any free online tool.

   • Paste the stringified JSON in the schema field of the API request body.

   • Send the API request. If your schema already exists, use the PUT method instead of POST in the API call.

4. The attributeSelector object helps you choose the scope at which your custom deployment schema will take effect.

Using Advanced (YAML)

If you are an advanced user wishing to perform additional configurations, you may switch to Advanced (YAML) for modifications.

Refer the respective templates to view the YAML details.

Application Metrics

Depending on the chart type and version you select, application metrics of your application may be viewed. This includes:

• Status codes 2xx, 3xx, 5xx

• Throughput

• Latency ...and many more

Enable Show application metrics toggle to view the application metrics on the App Details page.

IMPORTANT: Enabling application metrics introduces a sidecar container to your main container which may require some additional configuration adjustments. We recommend you to do load test after enabling it in a non-production environment before enabling it in production environment.

Select Save & Next to save your configurations.

The CI pipeline includes Pre and Post-build steps to validate and introduce checkpoints in the build process. The pre/post plugins allow you to execute some standard tasks, such as Code analysis, Load testing, Security scanning etc. You can build custom pre-build/post-build tasks or select one of the standard preset plugins provided by Devtron.

Preset plugin is an API resource which you can add within the CI build environment. By integrating the preset plugin in your application, it helps your development cycle to keep track of finding bugs, code duplication, code complexity, load testing, security scanning etc. You can analyze your code easily.

Devtron CI pipeline includes the following build stages:

• Pre-Build Stage: The tasks in this stage run before the image is built.

• Build Stage: In this stage, the build is triggered from the source code (container image) that you provide.

• Post-Build Stage: The tasks in this stage are triggered once the build is complete.

Before you begin

Make sure you have before you start configuring Pre-Build or Post-Build tasks.

Configuring Pre/Post-build Tasks

Each Pre/Post-build stage is executed as a series of events called tasks and includes custom scripts. You can create one or more tasks that are dependent on one another for execution. In other words, the output variable of one task can be used as an input for the next task to build a CI runner. The tasks will run following the execution order.

The tasks can be re-arranged by drag-and-drop; however, the order of passing the variables must be followed.

You can create a task either by selecting one of the available preset plugins or by creating a custom script.

Creating Pre/Post-build Tasks

Lets take Codacy as an example and configure it in the Pre-Build stage in the CI pipeline for finding bugs, detecting dependency vulnerabilities, and enforcing code standards.

• Go to the Applications and select your application from the Devtron Apps tabs.

• Go to the App Configuration tab, click Workflow Editor.

• Select the build pipeline for configuring the pre/post-build tasks.

• On the Edit build pipeline, in the Pre-Build Stage, click + Add task.

• Select Codacy from PRESET PLUGINS.

• Enter a relevant name or codacy in the Task name field. It is a mandatory field.

• Enter a descriptive message for the task in the Description field. It is an optional field. Note: The description is available by default.

• In the Input Variables, provide the information in the following fields:

• In Trigger/Skip Condition, set the trigger conditions to execute a task or Set skip conditions. As an example: CodacyEndpoint equal to https://app.codacy.com. Note: You can set more than one condition.

• In Pass/Failure Condition set the conditions to execute pass or fail of your build. As an example: Pass if number of issues equal to zero. Note: You can set more than one condition.

• Click Update Pipeline.

• Go to the Build & Deploy, click the build pipeline and start your build.

• Click Details on the build pipeline and you can view the details on the Logs.

Execute custom script

1. On the Edit build pipeline screen, select the Pre-build stage.

2. Select + Add task.

3. Select Execute custom script.

Custom script - Shell

• Select the Task type as Shell.

Consider an example that creates a Shell task to stop the build if the database name is not "mysql". The script takes 2 input variables, one is a global variable (DOCKER_IMAGE), and the other is a custom variable (DB_NAME) with a value "mysql". The task triggers only if the database name matches "mysql". If the trigger condition fails, this Pre-build task will be skipped and the build process will start. The variable DB_NAME is declared as an output variable that will be available as an input variable for the next task. The task fails if DB_NAME is not equal to "mysql".

• Select Update Pipeline.

Here is a screenshot with the failure message from the task:

Custom script - Container image

• Select the Task type as Container image.

This example creates a Pre-build task from a container image. The output variable from the previous task is available as an input variable.

• Select Update Pipeline.

Preset Plugins

What's next

Introduction

This configuration is an extension of the settings present in of Devtron. Therefore, make sure you read it before making any changes to your app configuration.

The application-level GitOps configuration offers the flexibility to add a custom Git repo (as opposed to Devtron auto-creating a repo for your application).

Adding Custom Git Repo for GitOps

For Devtron Apps

1. Go to Applications → Devtron Apps (tab) → (choose your app) → App Configuration (tab) → GitOps Configuration.
2. Assuming a GitOps repo was not added to your application earlier, you get 2 options:

   • Auto-create repository - Select this option if you wish to proceed with the default behavior. It will create a repository automatically, named after your application with a prefix. Thus saving you the trouble of creating one manually.

   • Commit manifests to a desired repository - Select this option if you wish to add a custom repo that is already created with your . Enter its link in the Git Repo URL field.

1. Click Save.

For Helm Apps

2. Click Configure & Deploy.
3. After you enter the App Name, Project, and Environment; an option to choose the deployment approach (i.e., Helm or GitOps) would appear. Select GitOps.

1. • Auto-create repository

   • Commit manifests to a desired repository
2. Enter your custom Git Repo URL, and click Save.

Next, you may proceed to deploy the chart.

Creating CI Pipeline

A CI Workflow can be created in one of the following ways:

• Sync with Environment

• Create a Job

Each method has different use-cases that can be tailored according the needs of the organization.

1. Build and Deploy from Source Code

Build and Deploy from Source Code workflow allows you to build the container image from a source code repository.

1. From the Applications menu, select your application.

2. On the App Configuration page, select Workflow Editor.

3. Select + New Workflow.

4. Select Build and Deploy from Source Code.

5. Enter the following fields on the Create build pipeline window:

Advanced Options

The Advanced CI Pipeline includes the following stages:

• Pre-build stage: The tasks in this stage are executed before the image is built.

• Build stage: In this stage, the build is triggered from the source code that you provide.

• Post-build stage: The tasks in this stage will be triggered once the build is complete.

Build Stage

Go to the Build stage tab.

Source type

Branch Fixed

This allows you to trigger a CI build whenever there is a code change on the specified branch.

Enter the Branch Name of your code repository.

Branch Regex

Branch Regex allows users to easily switch between branches matching the configured Regex before triggering the build pipeline. In case of Branch Fixed, users cannot change the branch name in ci-pipeline unless they have admin access for the app. So, if users with Build and Deploy access should be allowed to switch branch name before triggering ci-pipeline, Branch Regex should be selected as source type by a user with Admin access.

For example if the user sets the Branch Regex as feature-*, then users can trigger from branches such as feature-1450, feature-hot-fix etc.

Pull Request

This allows you to trigger the CI build when a pull request is created in your repository.

To trigger the build from specific PRs, you can filter the PRs based on the following keys:

Select the appropriate filter and pass the matching condition as a regular expression (regex).

Select Create Pipeline.

Tag Creation

This allows you to trigger the CI build whenever a new tag is created.

To trigger the build from specific tags, you can filter the tags based on the author and/or the tag name.

Select the appropriate filter and pass the matching condition as a regular expression (regex).

Select Create Pipeline.

Scan for Vulnerabilities

Custom Image Tag Pattern

This feature helps you apply custom tags (e.g., v1.0.0) to readily distinguish container images within your repository.

1. Enable the toggle button as shown below.
2. You can write an alphanumeric pattern for your image tag, e.g., test-v1.0.{x}. Here, 'x' is a mandatory variable whose value will incrementally increase with every build. You can also define the value of 'x' for the next build trigger in case you want to change it.

1. Click Update Pipeline.

2. Now, go to Build & Deploy tab of your application, and click Select Material in the CI pipeline.
3. Choose the git commit you wish to use for building the container image. Click Start Build.
4. The build will initiate and once it is successful the image tag would reflect at all relevant screens:

   • Build History

   • Docker Registry

   • CD Pipeline (Image Selection)

2. Linked Build Pipeline

If one code is shared across multiple applications, Linked Build Pipeline can be used, and only one image will be built for multiple applications because if there is only one build, it is not advisable to create multiple CI Pipelines.

1. From the Applications menu, select your application.

2. On the App Configuration page, select Workflow Editor.

3. Select + New Workflow.

4. Select Linked Build Pipeline.

5. On the Create linked build pipeline screen:

   • Search for the application in which the source CI pipeline is present.

   • Select the source CI pipeline from the application that you selected above.

   • Enter a new name for the linked CI pipeline.
6. Click Create Linked CI Pipeline.

Thereafter, the source CI pipeline will indicate the number of Linked CI pipelines. Upon clicking it, it will display the child information as shown below. It reveals the applications and environments where Linked CI is used for deployment.

After creating a linked CI pipeline, you can create a CD pipeline.

3. Deploy Image from External Service

For CI pipeline, you can receive container images from an external services via webhook API.

You can use Devtron for deployments on Kubernetes while using an external CI tool such as Jenkins or CircleCI. External CI feature can be used when the CI tool is hosted outside the Devtron platform. However, by using an external CI, you will not be able to use some of the Devtron features such as Image scanning and security policies, configuring pre-post CI stages etc.

• To configure Git Repository, you can add any Git repository account (e.g., dummy account) and click Next.

• To configure the Container Registry and Container Repository, you can leave the fields blank or simply add any test repository and click Save & Next.

• On the Workflow Editor page, click New Workflow and select Deploy image from external service.

• On the Deploy image from external source page, provide the information in the following fields:

• Click Create Pipeline. A new CI pipeline will be created for the external source. To get the webhook URL and JSON sample payload to be used in external CI pipeline, click Show webhook details.

• On the Webhook Details page, you have to authenticate via API token to allow requests from an external service (e.g. Jenkins or CircleCI).

• For authentication, only users with super-admin permissions can select or generate an API token:

  • Or use Auto-generate token to generate the API token with the required permissions. Make sure to enter the token name in the Token name field.
• To allow requests from the external source, you can request the API by using:

  • Webhook URL

  • cURL Request

Webhook URL

HTTP Method: POST

API Endpoint: https://{domain-name}/orchestrator/webhook/ext-ci/{pipeline-id}

JSON Payload:

You can also select metadata to send to Devtron. Sample JSON will be generated accordingly. You can send the Payload script to your CI tools such as Jenkins and Devtron will receive the build image every time the CI pipeline is triggered or you can use the Webhook URL, which will build an image every time CI pipeline is triggered using Devtron Dashboard.

Sample cURL Request

Response Codes

Integrate with External Sources - Jenkins or CircleCI

• On the Jenkins dashboard, select the Jenkins job which you want to integrate with the Devtron dashboard.

• Go to the Configuration > Build Steps, click Add build step, and then click Execute Shell.

• Enter the cURL request command.

• Make sure to enter the API token and dockerImage in your cURL command and click Save.

Now, you can access the images on the Devtron dashboard and deploy manually. In case, if you select Automatic deployment option, then your application will be deployed automatically everytime a new image is received.

Similarly, you can also integrate with external source such as CircleCI by:

• Select the job on the CircleCI dashboard and click Configuration File.

• On the respective job, enter the cURL command and update the API token and dockerImage in your cURL command.

Updating CI Pipeline

You can update the configurations of an existing CI Pipeline except for the pipeline's name. To update a pipeline, select your CI pipeline. In the Edit build pipeline window, edit the required stages and select Update Pipeline.

Deleting CI Pipeline

You can only delete a CI pipeline if there is no CD pipeline created in your workflow.

To delete a CI pipeline, go to App Configurations > Workflow Editor and select Delete Pipeline.

Extras

Configuring Webhook

For GitHub

1. Go to the Settings page of your repository and select Webhooks.

2. Select Add webhook.

3. In the Payload URL field, enter the Webhook URL that you get on selecting the source type as "Pull Request" or "Tag Creation" in Devtron the dashboard.

4. Change the Content-type to application/json.

5. In the Secret field, enter the secret from Devtron the dashboard when you select the source type as "Pull Request" or "Tag Creation".

1. Under Which events would you like to trigger this webhook?, select Let me select individual events. to trigger the webhook to build CI Pipeline.

2. Select Branch or tag creation and Pull Requests.

3. Select Add webhook.

For Bitbucket Cloud

1. Go to the Repository settings page of your Bitbucket repository.

2. Select Webhooks and then select Add webhook.

1. Enter a Title for the webhook.

2. In the URL field, enter the Webhook URL that you get on selecting the source type as "Pull Request" or "Tag Creation" in the Devtron dashboard.

3. Select the event triggers for which you want to trigger the webhook.

4. Select Save to save your configurations.

Prerequisites: Chart version should be > 4.14.0

External Secrets Operator is a Kubernetes operator that integrates external secret management systems like AWS Secrets Manager, HashiCorp Vault, Google Secrets Manager, Azure Key Vault and many more. The operator reads information from external APIs and automatically injects the values into a Kubernetes Secret.

Install External Secret Operator

Before creating any external secrets on Devtron, External Secret Operator must be installed on the target cluster. External Secret Operator allows you to use external secret management systems (e.g., AWS Secrets Manager, Hashicorp Vault, Azure Secrets Manager, Google Secrets Manager etc.) to securely inject secrets in Kubernetes.

You can install External Secrets Operator using charts store:

1. Go to charts store.

2. Search chart with name external-secrets.

2. Deploy the chart.