summaryrefslogtreecommitdiff
path: root/icktool.mdwn
blob: 5d8d2d30771c5c2ef2968de3ac0a792d5fc474e7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
[[!meta title="Using icktool"]]

Icktool is a command line program that uses the ick controller API to
manage projects and pipelines and querying status.

Installation
-----------------------------------------------------------------------------

Currently, you are best off running icktool from the [ick2.git][] source
code repository:

    git clone git://git.liw.fi/ick2
    cd ick2
    ./icktool --help

[ick2.git]: http://git.liw.fi/ick2

Alternatively, you can install the Debian package from
<http://code.liw.fi/debian/>.


Configuration
-----------------------------------------------------------------------------

Create the file `~/.config/icktool/icktool.yaml` with the following
content:

    config:
        controller: https://ick2
        verify-tls: no

Create the file `~/.config/icktool/credentials.conf` with the following
content:

    [https://ick2/token]
    client_id = admin
    client_secret = qwert

Change the `controller` line and the first line of `credentials.conf`
to be the URL to your controller.

Change `verify-tls` to `yes` if you have a CA-signed TLS certificate,
such as by Let's Encrypt.


Using
-----------------------------------------------------------------------------

To see all projects and pipelines use the `status` command:

    $ ./icktool status
    project | build_status | log_id
    ------- | ------------ | ------
    $ 

There should be no projects initially. To create some, create a file
`hello.ick` with the following content:

    projects:

      - project: say_hello
        parameters:
          target: world
        pipelines:
          - greet

    pipelines:

      - pipeline: greet
        parameters:
          - target
        actions:
          - shell: |
              t="$(params | jq -r .target)"
              echo "hello, $t"
            where: host

[jq][] is a handy command line tool for doing things with data in JSON
form. Here it is used to extract the value of a parameter. `params` is
a shell function provided by ick that outputs all parameters as JSON.

[jq]: https://github.com/stedolan/jq

Tell the controller about the new project:

    ./icktool make-it-so hello.ick

Trigger a build:

    ./icktool trigger say_hello

Check status (repeatedly until the build finishes):

    watch ./icktool status

Check the build log (you can run this while the build happens, as
well):

    ./icktool show-latest-log say_hello

Get help on command line use:

    ./icktool --help
    ./icktool help
    ./icktool help make-it-so


Triggering builds from version control servers, etc
-----------------------------------------------------------------------------

To trigger a build of project foo, access the
`https://controller/projects/foo/+trigger` (HTTP GET method, no
authentication needed).