From 8c491d3b86ce861fc4e192d7a21502ef220a763c Mon Sep 17 00:00:00 2001 From: David Dooling Date: Thu, 29 Oct 2020 15:16:49 -0500 Subject: [PATCH] Improve container skill page Improve container skill and payload docs. Add cron scheduling. [changelog:changed] --- docs/authoring/container-skills.md | 69 ++++++++++++++++++------------ docs/authoring/payloads.md | 19 +++++--- 2 files changed, 55 insertions(+), 33 deletions(-) diff --git a/docs/authoring/container-skills.md b/docs/authoring/container-skills.md index ceece4ae1..40582f0c3 100644 --- a/docs/authoring/container-skills.md +++ b/docs/authoring/container-skills.md @@ -1,19 +1,25 @@ -Container skills run Docker images when an event happens. Since you define the -Docker image to run and you can also define custom events and event payloads, -container skills basically let you run _anything you want whenever you want_. In -other words, container skills provide a powerful tool to trigger or schedule any -task imaginable. - -This section describes the contract between a container skill and the skill -runtime. The information in this documentation provides details on what +The +[Docker Container Runner skill](https://go.atomist.com/catalog/skills/atomist/container-run-skill "Docker Container Runner Skill") +runs a Docker image when an event happens. Since you define the Docker image and +are able to define custom events and event payloads, container skills basically +let you run _anything you want whenever you want_. In other words, container +skills provide a powerful tool to trigger or schedule any task imaginable. + +> Use the Atomist Docker Container Runner skill to run anything you want +> whenever you want. + +For most use cases, you can go directly to the +[Docker Container Runner skill page](https://go.atomist.com/catalog/skills/atomist/container-run-skill "Docker Container Runner Skill") +and enable it. If you need more information, this page describes the contract +between a container skill and the skill runtime, providing details on what information is available to container skills and how they can interact with the Atomist runtime and other external systems like GitHub and Slack. ## Requirements -The container skill can use any Docker image that can be pulled from a public -Docker registry. There are no requirements for what needs to be installed in the -container. +The container skill can use any Docker image that can be pulled from a Docker +registry, either public or private. There are no requirements for what needs to +be installed in the container. ## Triggers @@ -39,13 +45,22 @@ skill. - **channel linked**: a chat channel is mapped to a GitHub repository - **new user**: a new chat user is created in the chat team - **user joined channel**: a new user joins a chat channel -- **Custom webhook**: user-defined trigger (see below) +- **Advanced**: + - **Cron schedule**: scheduled using cron expression + - **Custom webhook**: user-defined trigger When the skill is executed, it receives the details of the event that triggered its execution as a JSON object provided the contents of the file pointed to by the `ATOMIST_PAYLOAD` environment variable. The data properties available in the **GitHub** and **Chat** events are provided by those platforms. For details on -the specific payloads, see the [Skill Trigger Payloads](payloads.md). +the payloads of the different triggers, see the +[skill trigger payloads](payloads.md). + +The **Cron schedule** trigger provides a mechanism to execute container skills +at regular intervals using a cron expression. A cron expression is of the format +`MINUTES HOURS DATES MONTHS DAYS`. See +[CRON Expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) for valid +cron expression syntax. The **Custom webhook** trigger provides a generic and extensible way to trigger executions of the container skill and provide it with arbitrary data payloads. @@ -148,8 +163,8 @@ execution echo '{ "code": 0, "reason": "Skill failed with some strange error" }' > "$ATOMIST_STATUS" ``` -`code`, `reason` and `visibility` (setting visibility to `hidden` will hide the -skill execution from the UI) are supported. +The `code`, `reason` and `visibility` (setting visibility to `hidden` will hide +the skill execution from the UI) properties are supported. ## Chat messages @@ -187,25 +202,23 @@ blocks. Refer to the Slack documentation to learn more about acceptable messages. When writing files to `$ATOMIST_MESSAGES_DIR` it is important to not re-use file -names as files are only processed for sending once. - -### Example +names as each file is only processed for sending once. The following example shows a simple Slack message that gets send into the _#general_ channel of your Chat integration: ```console echo '{ - "channels": ["general"], - "body": "Hello world!" + "channels": ["general"], + "body": "Hello world!" }' > $ATOMIST_MESSAGES_DIR/hello.json ``` ## Persisting changes to cloned repository Changes to the repository contents can be automatically committed and pushed to -the remote. A container-skill can indicate the desire to push changes back by -writing a JSON file to `$ATOMIST_PUSH`. +the Git remote. A container-skill can indicate the desire to push changes back +by writing a JSON file to `$ATOMIST_PUSH`. The file has to follow this structure: @@ -266,9 +279,9 @@ cache will be restored if it was previously stored. ## Secrets Secrets that get configured and mapped to environment variable names will be -available from within the container as environment variable values. - -### Example +available from within the container as environment variable values. To use +secrets in your container skill, you must first create the secret and then map +it to an environment variable: 1. Configure your secrets from the **Manage > Integrations** page of your Atomist workspace. @@ -278,6 +291,6 @@ available from within the container as environment variable values. ![Secrets](images/secret-map.png) - In this example, we've added the _Firebase token (prod)_ to our skill - configuration. The token is accessible from the `FIREBASE_TOKEN` environment - variable. + In this example, we've added the _ZenHub token_ secret to our skill + configuration. The token is accessible as the value of the `ZENHUB_TOKEN` + environment variable within the container. diff --git a/docs/authoring/payloads.md b/docs/authoring/payloads.md index 69b35d650..2559bccbe 100644 --- a/docs/authoring/payloads.md +++ b/docs/authoring/payloads.md @@ -1,8 +1,8 @@ -The different event types that trigger execution of a container skill make -different information available to the skill via the file pointed to by the -`ATOMIST_PAYLOAD` environment variable. The following sections detail the JSON -object make available in the contents of the `ATOMIST_PAYLOAD` file for the -different trigger event types. +The different event types that trigger execution of a skill make different +information available to the skill via the file pointed to by the +`ATOMIST_PAYLOAD` environment variable. The following sections give examples of +the JSON object make available in the contents of the `ATOMIST_PAYLOAD` file for +the different trigger event types. ## GitHub > branch @@ -1489,3 +1489,12 @@ different trigger event types. } } ``` + +## Cron schedule + +```json +{ + "configurationName": "Docker Container Runner", + "parameterName": "schedule" +} +```