Eventline is now open source and available on GitHub !

If you are still using the old Eventline platform, contact us to migrate to the new service, and head to the new documentation website for more information.

Your first pipeline

Goal

In this tutorial, you will create your first Eventline pipeline from scratch.

While Eventline resources can be deployed manually, doing so automatically would be convenient. Most Eventline resources are managed as YAML documents, and keeping them in a Git repository feels natural. We will therefore install a mechanism to deploy resources every time new commits are pushed.

Prerequisites

You will need a few things to complete this tutorial:

  • A computer running either Linux, *BSD or MacOS.
  • Basic knowledge of shell.
  • Basic knowledge of Git.
  • A GitHub account.
  • An Eventline account.

Preparations

Eventline client

We will start by installing evcli, the command line program used to interact with Eventline:

curl -sSLf https://download.eventline.net/evcli-install | sh -

Make sure it is correctly installed by running evcli version. If the program cannot be found, make sure that the PATH environment variable contains the /usr/local/bin directory.

On the Eventline interface, go to the “API keys” tab of “Account” page and create a new API key named evcli. Copy the key and configure evcli to use it:

evcli set-config api.key <key>

Git repository

You will need a repository to store Eventline resource files. Create a new one named eventline-default on your GitHub account; you will use it to store Eventline resources.

Warning
Make sure to create a private repository to protect information about your technical processes.

In this document, we will assume the repository is available at https://github.com/example/eventline-default. In the following code fragments, replace example by the name of your account in all commands.

On your machine, create the repository:

mkdir eventline-default
cd eventline-default
git init .
git remote add origin git@github.com:example/eventline-default.git

Identities

Identities are used to safely store credentials on Eventline.

Github

We will first create an identity which will allow Eventline to connect to GitHub. Go to the “Identities” page, and create an identity named github. Select the github connector and the oauth2 type.

Enter the name of your GitHub account in the “Username” field, then click on the “Submit” button.

You will be redirected to GitHub in order to authorize the connection.

SSH

We then need an identity to clone the repository during the execution of the task. We will access the repository using SSH, so we will need a SSH key.

Create a SSH key:

ssh-keygen -t ecdsa -f eventline-ssh

Go to the “Settings” page of your GitHub account, select the “SSH and GPG keys” menu entry, and create a new SSH key using the content of the eventline-ssh.pub file which was created by the previous command.

On the Eventline interface, create a new identity named ssh. Select the generic connector and the ssh_key type. Copy the content of the eventline-ssh file to the “Private key” field.

Eventline

Finally we need an identity which will be used to connect to Eventline in the task. Create a new identity named evcli. This time, select the eventline connector and the api_key type. Enter the API key you generated above in the “API key” field.

Info

If you forgot the API key, you can retrieve it from the configuration of evcli. Just use the following command:

evcli get-config api.key

You can now see these three identities in the identity list.

Writing the pipeline

First we need to initialize the Eventline project associated with this repository:

evcli initialize-project default .

The resulting eventline-project.json file must be committed.

Your new repository will contain resource files for the default Eventline project. Your are free to organize resources using directories as you see fit. In this tutorial, we will store resources in the deployment directory.

Also note that the name of the files does not matter to Eventline: feel free to name them as you see fit.

We will need three resources:

  • A trigger, to react to commits being pushed to the repository.
  • A pipeline, which will be called by the trigger.
  • A task to be executed by the pipeline.

Trigger

Create deployment/trigger.yaml with the following content:

type: "trigger"
version: 1
name: "deployment-push"
data:
  connector: "github"
  event: "push"
  parameters:
    organization: "example"
    repository: "eventline-default"
  identity: "github"
  pipelines:
    - "deployment"

We reference the push event in the github connector since we want to react to a set of commits pushed to a GitHub repository. The set of parameters indicates which GitHub organization and repository we want to watch.

We then select the identity which will be used by Eventline to create the GitHub hook. We use the github identity we created in the previous section, therefore Eventline will use the GitHub token we provided.

Finally, we indicate the list of pipelines which will be called when the trigger is activated, i.e. when a set of commits have been pushed. The deployment pipeline will be defined next.

Pipeline

Create deployment/pipeline.yaml with the following content:

type: "pipeline"
version: 1
name: "deployment"
data:
  tasks:
    - task: "deploy-project"

The pipeline is even simpler than the trigger: we only have one task to execute.

Task

Create deployment/task-deploy-project.yaml with the following content:

type: "task"
version: 1
name: "deploy-project"
data:
  runtime:
    name: "container"
    parameters:
      image: "alpine:latest"
  identities:
    - "ssh"
    - "evcli"
  environment:
    GIT_SSH_COMMAND: "ssh -i /eventline/identities/ssh/private_key"
  steps:
    - label: "install dependencies"
      code: |
        apk update
        apk add curl git openssh
    - label: "install evcli"
      code: |
        curl -sSLf https://download.eventline.net/evcli-install | sh -
    - label: "clone the repository"
      code: |
        mkdir -p $HOME/.ssh
        ssh-keyscan -H github.com >> $HOME/.ssh/known_hosts
        git clone git@github.com:example/eventline-default.git
        cd eventline-default
        revision=$(cat /eventline/event/new_revision)
        git reset --hard $revision
    - label: "deploy the project"
      code: |
        cd eventline-default
        evcli deploy-project

The task is a bit more complicated. We start by configuring how the task will be executed: it will run in a container, and will use Alpine Linux for convenience.

We then list the identities which will be available during execution. In our case, we will need access to the ssh identity to be able to clone the repository, and we will use the evcli identity to deploy project files.

To clone the Git repository, we will need to use SSH key stored in the github identity. Identity data are injected as files in /eventline/identities/<identity-name>/<field-name>. We define the GIT_SSH_COMMAND environment variable to tell git to use the private key of the ssh identity when cloning the repository.

Finally we can define a list of steps. Each step is a script which will be executed in the container. We go through the following steps:

  1. Installing git, to be able to clone the project.
  2. Installing evcli, to be able to deploy the project.
  3. Clone the repository containing the resource files of the project, and select the revision referenced in the event.
  4. Deploy the project to the Eventline platform.

Deploying the project

We need to do the first deployment manually, using evcli:

evcli deploy-project

Note that we do not need to provide the name of the project: evcli will obtain it from the eventline-project.json file which was created in our repository.

At this point, resources are deployed on the Eventline platform, and you can visualize them on the “Resources” page.

Testing the pipeline

We are now going to make sure the pipeline works as expected.

Commit and push the content you created:

git add .
git commit -m 'first pipeline for project deployment'
git push origin HEAD

Go to the “Pipelines” page on the Eventline interface. You should see the deployment pipeline and its last status.

Clicking on the “View” button will lead you to the page listing all executions of the pipelines. Click on the “View” button of the last execution to show detailed information.

If the pipeline succeeded, congratulations, you completed the tutorial!

If it failed, click on the task which failed: the task page includes the output of each executed step so that you can understand the error. Cannot figure out what went wrong? Contact our support for assistance.