About the SDM
The software delivery machine is a service that runs automations in response to events like pushes and builds. See architecture for a high-level view.
- is event driven: the SDM performs actions in response to events. The most significant event is a code push. The response to this event is defined by goals. The response to other events (repository or issue creation, for instance) is defined by listeners.
- uses common APIs across different automation scenarios. These let you write the important code specifying what you want to do, while calling APIs for the common work. For instance, the Project API lets you inspect and update the repository contents.
Your SDM is in TypeScript. Start with our code and add what you choose.
This section documents creating, building, and running an SDM, and details the structure and organization of a typical SDM project.
To get started in local mode, make sure you have:
This page will help you:
- create an SDM project
- spin up your SDM
- know where to add functionality to your SDM
For the quickest path to seeing an SDM do something, use the Quick Start instead.
Creating an SDM project
The Atomist CLI will generate a starter SDM for you.
atomist create sdm
For “Type of SDM to create, “Choose “blank” to start with an empty SDM, or “spring” to start with an SDM that does useful things for Java Spring services.
For “name of the target repository” enter a name for your SDM.
For “target-owner” enter a name for the owner of your project. This corresponds to the GitHub/GitLab organization or BitBucket project you would put the repository under.
Look in $HOME/atomist/target-owner/name for the new SDM.
If you prefer the manual route, you can always fork the empty-sdm project on GitHub.
Looking at the code
You can use whatever editor or IDE you like. We recommend VSCode because it is built for TypeScript (among other languages), it’s a good IDE, and it’s free. With TypeScript and an IDE like VSCode, you get autocompletion that helps you discover functionality in the SDM framework.
npm install first so that your IDE will see library code. In Node, all dependencies
are stored within the project, under the directory
npm is the dependency manager
that gets them there. The node_modules directory is listed in
.gitignore, so it won’t be committed.
Start your inquiry in
index.ts. When an SDM starts up, it looks here to find its configuration.
configuration object has opportunities for many, many configuration options. Click into the Configuration type
or check the API Docs if you’re curious.
The important part, where you’re going to add to your personal SDM, is the function passed to
Unless you change it, that function is called
Click into the
machine function in your IDE, or open
lib/machine/machine.ts to find it.
This function instantiates
and then returns a SoftwareDeliveryMachine(API docs).
Inside this function, add functionality to your SDM. You can:
- Add Goals to choose a flow to respond to code push
- Add listeners to various other events
- Add commands
- Add project generators
- Bring in extension packs
Building an SDM
npm run build
Starting an SDM
There are a few different ways to start the SDM,
depending on how you are running it. If you are running the
SDM locally, you can use the standard npm
If you are writing your own SDMs, you probably want a more
responsive testing environment, having the client restart any time you
make changes to the source code. This development
flow is available with the
npm run autostart
When you deploy your SDM to production, check the recommendations under Deploying your SDM.
Control-C will stop the client. Restart it after code changes with
atomist start again.
SDM projects are organized and behave like any standard TypeScript project.
package.json file defines the metadata and dependencies for the
project. In addition, this file defines the standard “npm package
npm run commands, typically available in Node.js
projects. Here’s a summary of the npm package scripts available in
most SDM projects.
||install all the required packages|
||run, refreshing when files change|
||run tests every time files change|
||lint, compile, and test|
||run tslint against the TypeScript|
||start the SDM|
lib directory contains the TypeScript source code.
This is the starting point when you want to look at what this SDM might do.
graphql directory contains
.graphql files defining
your GraphQL queries, subscriptions, and mutations. This
directory is optional, as you can define your GraphQL in strings
within the source code. That said, it is recommended that you define
your GraphQL in
.graphql files so you can realize the full benefit
of its type bindings in TypeScript.
lib/typings directory contains the auto-generated TypeScript
types for your GraphQL queries, subscriptions, and mutations.
node_modules directory contains all the project dependencies, as
defined in the
package.json and installed by npm.
scripts directory contains various ancillary scripts. For
example, this directory might have scripts for building the project on
CI, publishing the project as an Node.js package, and publishing the
Proceed to [add some functionality][add-functionality] to your SDM.