KOP GitOps - Triggers - Rafay Product Documentation

Overview

Triggers are external events that start a pipeline job. Two types of triggers are currently supported.

Webhooks
- Github
- Gitlab
- BitBucket
- Azure Repos
Cron Job based Repository Sync

Webhooks

External Git repos can be configured to send a webhook to the Controller. If the webhook payload satisfies the specified criteria, the pipeline job is started.

Provide a user friendly name for your webhook triggers
Select the repository from which the webhook will be received
Select type of repository (Webhook payloads are different for every provider)
Specify the "revision" to be monitored
Optionally, specify the "paths" for which the trigger will be activated
Optionally, configure trigger variables to customize your triggers

Cron Job

This is essentially a "periodic repository" sync operation that is performed as per configured schedule. When the sync operation detects that monitored files have been updated in the repository, it starts the pipeline job.

Unlike webhooks which are provider specific, repository sync operations will work on any Git compatible provider
Security considerations may prevent some organizations from using webhooks
Some organizations may view repository sync as more reliable relative to webhooks
Select a repository to monitor
Specify the branch (i.e. revision)
Optionally, specify the "paths" for which the trigger will be activated
Specify a Cron expression
Optionally, configure trigger variables to customize your triggers

Examples of common cron expressions:

At every minute is "* * * * *"
At every 5th minute is "*/5 * * * *"
At every 15th minute is "*/15 * * * *"
At every 30th minute is "*/30 * * * *"

Trigger Variables

Trigger variables can be dynamically "set" based on environmental data and from the "payload" received as part of the incoming webhook. These variables can be used in the stages of the "pipeline" allowing for "dynamic actions". Some stages in the pipeline can then be executed and some skipped based on a dynamic evaluation of the "trigger variables" that are set as part of a pipeline job. With this approach, the developer/operator just has to make the commit in Git with the "suitable metadata" and the correct "stage" in the pipeline will be automatically executed.

Some common examples are:

If commit user = John, only the "John" stage in the pipeline is executed
If commit message = "provision", the "provision cluster" stage in the pipeline is executed
If commit message = "deprovision", the "deprovision cluster" stage in the pipeline is executed

The trigger variables supported by the platform are:

Trigger Name	Description
trigger.name (StringType)	The user friendly name for the trigger
trigger.id (StringType)	The unique ID for the trigger
trigger.when (TimeType)	Timestamp for the trigger
trigger.payload (MapType)	The payload received from the repository as part of the webhook

See JSON payload example below shows the "payload" received as part of a webhook from a Git repository.

Example

In the example shown below, the following trigger variables are "dynamically set" and can then be used by the stages as part of a "pipeline job".

The value for the variable "cluster" is assigned from "trigger.payload.head_commit.message"
The value for the variable "user" is assigned from "trigger.payload.pusher.user"
The value for the variable "file" is assigned from "trigger.payload.commits[0].modified[0]"

{
  "ref": "refs/heads/main",
  "before": "ab3a10e498ebb976f6d9beb6c33e8fca9fa641f4",
  "after": "fd1ad213c0c8deca1782cac3612d41ca8737dfbb",
  "repository": {
    "id": 312689044,
    "node_id": "MDEwOlJlcG9zaXRvcnkzMTI2ODkwNDQ=",
    "name": "apps",
    "full_name": "hardik-rafay/apps",
    "private": true,
    "owner": {
      "name": "hardik-rafay",
      "email": "61439574+hardik-rafay@users.noreply.github.com",
      "login": "hardik-rafay",
      "id": 61439574,
      "node_id": "MDQ6VXNlcjYxNDM5NTc0",
      "avatar_url": "https://avatars.githubusercontent.com/u/61439574?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/hardik-rafay",
      "html_url": "https://github.com/hardik-rafay",
      "followers_url": "https://api.github.com/users/hardik-rafay/followers",
      "following_url": "https://api.github.com/users/hardik-rafay/following{/other_user}",
      "gists_url": "https://api.github.com/users/hardik-rafay/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/hardik-rafay/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/hardik-rafay/subscriptions",
      "organizations_url": "https://api.github.com/users/hardik-rafay/orgs",
      "repos_url": "https://api.github.com/users/hardik-rafay/repos",
      "events_url": "https://api.github.com/users/hardik-rafay/events{/privacy}",
      "received_events_url": "https://api.github.com/users/hardik-rafay/received_events",
      "type": "User",
      "site_admin": false
    },
    "html_url": "https://github.com/hardik-rafay/apps",
    "description": null,
    "fork": false,
    "url": "https://github.com/hardik-rafay/apps",
    "forks_url": "https://api.github.com/repos/hardik-rafay/apps/forks",
    "keys_url": "https://api.github.com/repos/hardik-rafay/apps/keys{/key_id}",
    "collaborators_url": "https://api.github.com/repos/hardik-rafay/apps/collaborators{/collaborator}",
    "teams_url": "https://api.github.com/repos/hardik-rafay/apps/teams",
    "hooks_url": "https://api.github.com/repos/hardik-rafay/apps/hooks",
    "issue_events_url": "https://api.github.com/repos/hardik-rafay/apps/issues/events{/number}",
    "events_url": "https://api.github.com/repos/hardik-rafay/apps/events",
    "assignees_url": "https://api.github.com/repos/hardik-rafay/apps/assignees{/user}",
    "branches_url": "https://api.github.com/repos/hardik-rafay/apps/branches{/branch}",
    "tags_url": "https://api.github.com/repos/hardik-rafay/apps/tags",
    "blobs_url": "https://api.github.com/repos/hardik-rafay/apps/git/blobs{/sha}",
    "git_tags_url": "https://api.github.com/repos/hardik-rafay/apps/git/tags{/sha}",
    "git_refs_url": "https://api.github.com/repos/hardik-rafay/apps/git/refs{/sha}",
    "trees_url": "https://api.github.com/repos/hardik-rafay/apps/git/trees{/sha}",
    "statuses_url": "https://api.github.com/repos/hardik-rafay/apps/statuses/{sha}",
    "languages_url": "https://api.github.com/repos/hardik-rafay/apps/languages",
    "stargazers_url": "https://api.github.com/repos/hardik-rafay/apps/stargazers",
    "contributors_url": "https://api.github.com/repos/hardik-rafay/apps/contributors",
    "subscribers_url": "https://api.github.com/repos/hardik-rafay/apps/subscribers",
    "subscription_url": "https://api.github.com/repos/hardik-rafay/apps/subscription",
    "commits_url": "https://api.github.com/repos/hardik-rafay/apps/commits{/sha}",
    "git_commits_url": "https://api.github.com/repos/hardik-rafay/apps/git/commits{/sha}",
    "comments_url": "https://api.github.com/repos/hardik-rafay/apps/comments{/number}",
    "issue_comment_url": "https://api.github.com/repos/hardik-rafay/apps/issues/comments{/number}",
    "contents_url": "https://api.github.com/repos/hardik-rafay/apps/contents/{+path}",
    "compare_url": "https://api.github.com/repos/hardik-rafay/apps/compare/{base}...{head}",
    "merges_url": "https://api.github.com/repos/hardik-rafay/apps/merges",
    "archive_url": "https://api.github.com/repos/hardik-rafay/apps/{archive_format}{/ref}",
    "downloads_url": "https://api.github.com/repos/hardik-rafay/apps/downloads",
    "issues_url": "https://api.github.com/repos/hardik-rafay/apps/issues{/number}",
    "pulls_url": "https://api.github.com/repos/hardik-rafay/apps/pulls{/number}",
    "milestones_url": "https://api.github.com/repos/hardik-rafay/apps/milestones{/number}",
    "notifications_url": "https://api.github.com/repos/hardik-rafay/apps/notifications{?since,all,participating}",
    "labels_url": "https://api.github.com/repos/hardik-rafay/apps/labels{/name}",
    "releases_url": "https://api.github.com/repos/hardik-rafay/apps/releases{/id}",
    "deployments_url": "https://api.github.com/repos/hardik-rafay/apps/deployments",
    "created_at": 1605303332,
    "updated_at": "2021-05-14T07:29:13Z",
    "pushed_at": 1620977387,
    "git_url": "git://github.com/hardik-rafay/apps.git",
    "ssh_url": "git@github.com:hardik-rafay/apps.git",
    "clone_url": "https://github.com/hardik-rafay/apps.git",
    "svn_url": "https://github.com/hardik-rafay/apps",
    "homepage": null,
    "size": 14192,
    "stargazers_count": 0,
    "watchers_count": 0,
    "language": "Mustache",
    "has_issues": true,
    "has_projects": true,
    "has_downloads": true,
    "has_wiki": true,
    "has_pages": false,
    "forks_count": 0,
    "mirror_url": null,
    "archived": false,
    "disabled": false,
    "open_issues_count": 0,
    "license": null,
    "forks": 0,
    "open_issues": 0,
    "watchers": 0,
    "default_branch": "main",
    "stargazers": 0,
    "master_branch": "main"
  },
  "pusher": {
    "name": "hardik-rafay",
    "email": "61439574+hardik-rafay@users.noreply.github.com"
  },
  "sender": {
    "login": "hardik-rafay",
    "id": 61439574,
    "node_id": "MDQ6VXNlcjYxNDM5NTc0",
    "avatar_url": "https://avatars.githubusercontent.com/u/61439574?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/hardik-rafay",
    "html_url": "https://github.com/hardik-rafay",
    "followers_url": "https://api.github.com/users/hardik-rafay/followers",
    "following_url": "https://api.github.com/users/hardik-rafay/following{/other_user}",
    "gists_url": "https://api.github.com/users/hardik-rafay/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/hardik-rafay/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/hardik-rafay/subscriptions",
    "organizations_url": "https://api.github.com/users/hardik-rafay/orgs",
    "repos_url": "https://api.github.com/users/hardik-rafay/repos",
    "events_url": "https://api.github.com/users/hardik-rafay/events{/privacy}",
    "received_events_url": "https://api.github.com/users/hardik-rafay/received_events",
    "type": "User",
    "site_admin": false
  },
  "created": false,
  "deleted": false,
  "forced": false,
  "base_ref": null,
  "compare": "https://github.com/hardik-rafay/apps/compare/ab3a10e498eb...fd1ad213c0c8",
  "commits": [
    {
      "id": "fd1ad213c0c8deca1782cac3612d41ca8737dfbb",
      "tree_id": "c9d4933c230e4a8d4c930bb078384cb52dfc78a5",
      "distinct": true,
      "message": "Update deployment.yaml",
      "timestamp": "2021-05-14T00:29:47-07:00",
      "url": "https://github.com/hardik-rafay/apps/commit/fd1ad213c0c8deca1782cac3612d41ca8737dfbb",
      "author": {
        "name": "Hardik Italia",
        "email": "61439574+hardik-rafay@users.noreply.github.com",
        "username": "hardik-rafay"
      },
      "committer": {
        "name": "GitHub",
        "email": "noreply@github.com",
        "username": "web-flow"
      },
      "added": [
      ],
      "removed": [
      ],
      "modified": [
        "helm/nginx/templates/deployment.yaml"
      ]
    }
  ],
  "head_commit": {
    "id": "fd1ad213c0c8deca1782cac3612d41ca8737dfbb",
    "tree_id": "c9d4933c230e4a8d4c930bb078384cb52dfc78a5",
    "distinct": true,
    "message": "Update deployment.yaml",
    "timestamp": "2021-05-14T00:29:47-07:00",
    "url": "https://github.com/hardik-rafay/apps/commit/fd1ad213c0c8deca1782cac3612d41ca8737dfbb",
    "author": {
      "name": "Hardik Italia",
      "email": "61439574+hardik-rafay@users.noreply.github.com",
      "username": "hardik-rafay"
    },
    "committer": {
      "name": "GitHub",
      "email": "noreply@github.com",
      "username": "web-flow"
    },
    "added": [
    ],
    "removed": [
    ],
    "modified": [
      "helm/nginx/templates/deployment.yaml"
    ]
  }
}