Skip to content

Project Configs

The workflow configs for a project must be defined in "project configs". These configs should be placed initially (before creating a project) or exported later (after creating a project) automatically when the predefined configuration will be used.

How can I edit the project configs?

You can edit it directly in the Codario project settings in a browser.

Example of the configs file

{
  "integrations": {
    "continuous_delivery": [
      {
        "credential": "ssh.server-alfa"
      },
      {
        "credential": "ssh.server-beta"
      }
    ],
    "collaboration_tool": {
      "credential": "slack-default"
    },
    "project_management_system": {
      "credential": "jira-default",
      "project": "project-key",
      "tracker": "Task",
      "priority": "Low",
      "task_status_to_codario_mapping": {
        "In Progress": "execute_update",
        "Done": "closed"
      },
      "task_status_from_codario_mapping": {
        "closed": "Done"
      },
      "visibility": {
        "comments": "role.Administrators"
      }
    },
    "git_provider": {
      "credential": "main-gitlab"
    }
  },
  "update_behavior": {
    "handle_packages": "dev_and_prod",
    "updates": {
      "regular": {
        "source_branch": "dev",
        "destination_branch": "updates/[task:id]",
        "auto_start_updates": "no",
        "skip_manual_testing": "no",
        "create_pull_request": {
           "target": ["master"]
        }
      },
      "vulnerable": {
        "source_branch": "dev",
        "destination_branch": "updates/[task:id]",
        "auto_start_updates": "no",
        "skip_manual_testing": "no",
        "create_pull_request": {
           "target": ["master"]
        }
      }
    }
  },
  "events": {
    "new_updates_available": [
      {
        "sendmail": {
          "emails": "[email protected],[email protected]",
          "subject": "Test subject - Composer Project",
          "message": "Test message - Composer Project",
          "cc": "",
          "bcc": ""
        }
      },
      {
        "sendmessage": {
          "title": "New updates available for \"[project:name]\"",
          "message": "We've found the new updates for your project.\n\nThe packages:\n[task:packages|, ][package:name]: [package:current-version] → [package:new-version][/task:packages]",
          "color": "#998877"
        }
      }
    ],
    "ready_to_test": [],
    "test_passed": [
      {
        "merge_branch": {
          "source": "source-branch",
          "delete_after_merge": "yes",
          "target": ["target-1", "target-2"],
          "ignore_result": "yes"
        }
      },
      {
        "add_git_tag": {
          "name": "task-[task:id]"
        }
      },
      {
        "url_request": {
          "url": "http://myproject.com/api/call",
          "type": "get",
          "body": {
            "task": "[task:id]"
          }
        }
      },
      {
        "ssh_script": {
          "connection": "ssh.server-alfa",
          "script": "pwd"
        }
      },
      {
        "accept_pull_request": {}
      }
    ],
    "test_failed": [
      {
        "decline_pull_request": {}
      }
    ],
    "closed": [],
    "failed": [
      {
        "sendmail": {
          "emails": "[email protected],[email protected]",
          "subject": "Test subject - Composer Project",
          "message": "Test message - Composer Project",
          "cc": "",
          "bcc": ""
        }
      }
    ]
  }
}

Bulk configs update

You can edit the configs for every project separately on project settings page. But sometimes you need to apply the same changes in configs for all (or part) of your projects. For such cases you can use "Bulk Configs Update" (placed on Projects Configs page).

To change some part of configs you need to know property name, action and value.

To better understand how it works, let's see the following configs example:

{
  "integrations": {
    "git_provider": {
      "credential": "main-gitlab",
      "target": ["master"]
    },
    ...
  },
  ...
}

Propose that you want to change credentials property to new-gitlab.

In this case you need use the following options:

  • property name: integrations.git_provider.credential
  • action: update
  • value: "new-gitlab"

Alright, let's see a more difficult example: you want to change not only credential property, but you also want to change target. This case can be covered as well:

  • property name: integrations.git_provider
  • action: update
  • value: {"credential": "new-gitlab", "target": ["stage", master"]}

Now let's suggest you want to delete integrations.git_provider property, then use the following options:

  • property name: integrations.git_provider
  • action: delete

If you want to add an action (f.e. merge_branch) to an event (f.e. test_passed), then use the following options:

  • property name: events.test_passed
  • action: add item
  • value: {"merge_branch": { "source": "master", "delete_after_merge": "yes", "target": ["update/[task:id]"], "ignore_result": "yes"}},

For example, you accidentally added 2nd merge branch action to test_passed event:

"events": {
  "test_passed": [
    {
      "merge_branch": {
        "source": "updates/[task:id]",
        "delete_after_merge": "yes",
        "target": [
          "master"
        ]
      }
    },
    {
      "merge_branch": {
        "source": "updates/[task:id]",
        "delete_after_merge": "yes",
        "target": [
          "master"
        ]
      }
    }
  ]
}

To delete second (duplicated) action use the following options:

  • property name: events.test_passed.1 (1 - the index in the test_passed array, indexes begin from 0)
  • action: delete

Explanation

Integrations

Project Manager System

Key: project_management_system.

Property Description
credential The alias of the corresponding credentials.
project The project name inside the project manager system.
tracker The tracker name inside the project manager system.
priority The priority for the tasks, which will be created with AG.
task_status_to_codario_mapping The mapping for the statuses, used for changing the statuses in a task of AG when in a project system manager a status of a corresponding task will be changed. Also there possible provide a mapping for the execute_update (despite the fact that it is implicit).
task_status_from_codario_mapping The mapping for the statuses, used for changing the statuses in a task of project system manager when in AG a status of a corresponding task will be changed.
visibility The visibility of different entities in the project management system. Right now available only comments key. Every project management system has different settings for this section, read more details on supported integrations page. Not required.
issue_subject The name of the issue in a project management system. Not required, use only if necessary to use the custom subject.

Collaboration tool

Key: collaboration_tool.

Property Description
credential The alias of the corresponding credentials.

Continuous Delivery

Key: continuous_delivery.

Contains multiple definitions, unlike other integration groups.

Property Description
credential The alias of the corresponding credentials.

Git Provider

Key: git_provider.

You will be able to also use accept_pull_request and decline_pull_request actions as well as create_pull_request property for "update types".

Property Description
credential The alias of the corresponding credentials of gitlab, github or bitbucket provider.

Update behavior

Key: update_behavior.

Contain sections with branches for updates. Allowed to use tokens.

Properties for Update behavior

Property Description
handle_packages Choose which packages should be checked. Available values: dev_and_prod (by default), prod_only. Not required.
updates Choose which types of packages should be checked and specify the necessary behavior for each of them. All details see below.

Available Update types

Type Description
regular The update type will be used for tasks without vulnerable packages. If no vulnerable section is provided, the tasks will include updates fixing vulnerabilities as well.
vulnerable The update type will be used for a task that contains at least one vulnerable package.
extra types for Drupal projects Additional special types are available for Drupal projects.

None of these types is required in the configs. Though, no update task will be created in this case.

If the regular section is not provided in a config, then an update task will be created only for packages that contain vulnerabilities and all dependent packages.

If only the regular section is provided, then an update task will be created for all available updates including updates fixing vulnerabilities. Hence, you should specify both sections (regular and vulnerable) only if you need use different behaviors for regular and vulnerable updates.

Properties for Update behavior type

Property Description
source_branch The source branch. Allowed to use tokens.
destination_branch The destination update branch. Allowed to use tokens.
auto_start_updates This property specified a method of the start update process for update tasks. Available values: yes, no.
skip_manual_testing This property specified which status will has a task after applying the update. If "yes" - "Test Passed", otherwise "Ready to Test". Available values: yes, no.
create_pull_request Add this property to create pull requests in the specified git_provider for update tasks. Has a required property target (the list of target branches for a pull request).

Events

The available events:

  • new_updates_available (a task has been created)
  • ready_to_test (updates have been applied and manual testing is enabled)
  • test_passed (test passed automatically or manually)
  • test_failed (test has been failed)
  • failed (some problem has been occurred: network problem, problem with access to repo, ...)
  • closed (a task has been closed)

Multiple stages for "Ready to test" event

The "Ready to test" event may have multiple stages, like "deploy-to-dev-env", "merge-from-dev-to-stage", etc.

A valid name of a multiple stage for "Ready to test" event is ready_to_test:NAME_OF_MULTIPLE_STAGE (f.e. ready_to_test:deploy-to-dev-env). A valid NAME_OF_MULTIPLE_STAGE can consist of "0-9, a-z, -" characters and has to be between 2 and 100 characters long.

If skip_manual_testing is equal to no, then a task will be moved to default ready_to_test stage. Any of the multiple stages for "Ready to test" may be executed in any order.

Multiple stages will be useful to provide a step-by-step build/deployment process for tasks. For example:

  • ready_to_test:deploy-to-dev-env
  • ready_to_test:merge-from-dev-to-stage
  • ready_to_test:deploy-to-stage-env
  • ready_to_test:merge-from-stage-to-master
  • ready_to_test:deploy-to-live-env

Each of the names should contain the executed action (like merge_branch, url_request, etc).

Global properties of Actions

Property Description
ignore_result Skip any errors during execution (and hence doesn't choose "Failed" state) of action if it is equal yes. Can be useful when result of execution of SSH script or merge request doesn't matter. Available values: yes, no (by default). Not required.
only_when Execute an action depends on a case. Available values: task:contains_vulnerable_packages (if an update task contains at least one vulnerable package), task:contains_no_vulnerable_packages (if an update task doesn't contain vulnerable packages), always (by default). Not required. The extra values are available for Drupal projects.

List of Actions

Send Mail

Key: sendmail.

Property Description
emails The list of emails, separate with comma. Allowed to use tokens.
subject The subject of an email. Allowed to use tokens.
message The message of an email. Allowed to use tokens.
cc The list of carbon copy emails, separate with comma.
bcc The list of blind carbon copy emails, separate with comma.

Send Message (to enabled Collaboration tool)

Key: sendmessage.

Property Description
title The subject of an email. Allowed to use tokens. Not required.
message The message of an email. Allowed to use tokens.
color The color for a line in Slack message (use #RRGGBB format). Not required.

Merge a branch

Key: merge_branch.

Property Description
source The source branch. Allowed to use tokens.
delete_after_merge The property, which defines the need to remove source branch after a merge. Available values: yes, no.
target The array of target branches. Allowed to use tokens.

Request a URL

Key: url_request.

Property Description
url The URL for request. Allowed to use tokens.
type Type of a request. Available values: post, get, head, put, delete, patch.
headers Headers for a request, will be used for this section. Allowed use tokens for keys and values. Not required.
auth Auth data for a request, will be used for this section. Allowed use tokens for keys and values. Not required.
body Body for a request. If specified a string will be used for this section, if an array - will be used for this section. Allowed use tokens for keys and values. Not required.

Execute a SSH script

Key: ssh_script.

Property Description
connection Name of a SSH connection (alias).
script BASH script which will be executed on your server. Allowed to use tokens.

Accept a Pull request

Key: accept_pull_request.

Available only if git_provider is defined in the integrations section.

Property Description
delete_source_branch The property, which defines the need to remove source branch after a merge. Available values: yes, no.

Decline a Pull request

Key: decline_pull_request.

Available only if git_provider is defined in the integrations section.

Property Description
delete_source_branch The property, which defines the need to remove source branch after a merge. Available values: yes, no.

Add a git tag

Key: add_git_tag.

Property Description
name The name of git tag to be added to the commit with packages' updates. If a tag exists already then just [1..N] postfix will be added to created git tag, f.e. task-XXX-1. Allowed to use tokens. If you want to use semver tags for commits with updates (f.e. codario-update-1.5.34), then just use a special [semver:patch+1] token. This token will find the latest semver tag and increase the patch part by 1.
separator The separator before postfix in git tag name. Not required, by default -.