@atomist/tslint-automation

This repository contains a development automation that automatically runs TSLint on every push of a TypeScript project. In doing so, it provides a central, convenient way for you to ensure all TypeScript projects in your organization are properly linted. This automation used the Atomist automation API.

The project uses the @atomist/automation-client node module to implement a local client that connects to the Atomist API.

Prerequisites

Below are brief instructions on how to get started running this project yourself. If you just want to use the core functionality of Atomist, see the Atomist documentation. For more detailed information on developing automations, see the Atomist Developer Guide.

GitHub account

You must have a GitHub account, either github.com or GitHub Enterprise (GHE). If you want to use Atomist with GHE, please contact Atomist. The remainder of these instructions assume you have a github.com account. If you do not already have a github.com account, you can create one.

To run automations, you will need a GitHub personal access token with "read:org" scope. You can create one yourself or use the Atomist CLI to do it for you (see below).

Atomist workspace

You also need to # with Atomist and create a workspace. Once you have a github.com account, you can # with Atomist at https://app.atomist.com/. Once you are registered with Atomist, you can create an Atomist workspace and add your GitHub user and/or organizations to that workspace.

Once you have created your Atomist workspace, take note of your Atomist workspace/team ID. You can always find your Atomist workspace ID on the workspace's settings page or, if you have added the Atomist app to Slack, you can send the Atomist bot the message team and it will tell you the workspace/team ID.

Slack

Atomist has a powerful Slack application, allowing you to see and act on your development activity right in Slack. Slack is not a requirement for using Atomist, but if you try it, you'll probably like it. If you do not have access to a Slack team, it is easy to create your own.

In your Slack team, install the Atomist app in Slack, click the button below.

Once installed, the Atomist bot will guide you through connecting Atomist, Slack, and GitHub.

Configuration

Once you have GitHub and Atomist set up, install the Atomist CLI and configure your local environment.

$ npm install -g @atomist/automation-client
$ atomist config

The second command does two things: records what Atomist workspace/team you want your automations running in and creates a GitHub personal access token with "repo" and "read:org" scopes.

The script will prompt you for your Atomist workspace/team ID, or you can supply it using the --team TEAM_ID command-line option. You can get your Atomist team ID from the settings page for your Atomist workspace or by typing team in a DM to the Atomist bot.

The script will prompt you for your GitHub credentials. It needs them to create the GitHub personal access token. Atomist does not store your credentials and only writes the generated token to your local machine.

The Atomist API client authenticates using a GitHub personal access token. The Atomist API uses the token to confirm you are who you say you are and are in a GitHub organization connected to the Slack team in which you are running the automations. In addition, it uses the token when performing any operations that access the GitHub API.

Running

You can run this automation using its Docker container, e.g., in Kubernetes, or locally.

Docker and Kubernetes

To download and run the Docker image of this project, run the following command

$ docker run --rm -e ATOMIST_TOKEN=YOUR_TOKEN -e ATOMIST_TEAMS=TEAM_ID \
    atomist/tslint-automation:VERSION

replacing YOUR_TOKEN and TEAM_ID with the token and team ID from your ~/.atomist/client.config.json created above by the atomist config command and VERSION with the latest release of this repo. Note that this will not be running any code from your local machine but the code in the Docker image.

To run the Docker image in a Kubernetes cluster, you can use the deployment spec from this repository as a starting point. Before creating the deployment resource, you will need to create a secret with the following command, replacing TOKEN and TEAM_ID as above.

$ kubectl create secret generic automation --from-file=$HOME/.atomist/client.config.json
$ kubectl create -f assets/kube/deployment.yaml

Locally

You will need to have Node.js installed. To verify that the right versions are installed, run:

$ node -v
v9.7.1
$ npm -v
5.6.0

The node version should be 8 or greater and the npm version should be 5 or greater.

Cloning the repository and installing dependencies

To get started run the following commands to clone the project, install its dependencies, and build the project:

$ git clone git@github.com:atomist/tslint-automation.git
$ cd tslint-automation
$ npm install
$ npm run build

Starting up the automation-client

You can run this repository locally, allowing you to change the source code of this project and immediately see the effects in your environment with the following command

$ npm run autostart

To run in a more traditional manner, build the project and then simple start it.

$ npm start

Using

This automation should run on every push in all of the GitHub organizations linked to your Atomist workspace.

Support

General support questions should be discussed in the #support channel in our community Slack team at atomist-community.slack.com.

If you find a problem, please create an issue.

Development

You will need to install node to build and test this project.

Build and Test

Command	Reason
npm install	install all the required packages
npm run build	lint, compile, and test
npm start	start the Atomist automation client
npm run autostart	run the client, refreshing when files change
npm run lint	run tslint against the TypeScript
npm run compile	compile all TypeScript into JavaScript
npm test	run tests and ensure everything is working
npm run autotest	run tests continuously
npm run clean	remove stray compiled JavaScript files and build directory

Release

Releases are handled by the Atomist Software Delivery Machine (SDM).

---

Created by Atomist. Need Help? Join our Slack team.