Octwilio

About

Octwilio is a project to combine the Octopus Deploy and Twilio APIs.

How it works

This project contains [Firebase] cloud functions for connecting Octopus Deploy and Twilio events. The functions handle Octopus Deploy subscription events as well as SMS messages to a Twilio phone number.

More details can be found in this blog series about building Octwilio.

Features

• Send SMS alert when an Octopus Deploy deployment requires approval
• Approve or reject a deployment via SMS
• Send SMS alerts for deployment events
• Endpoint for deployment notifications

How to use it

1. Create a copy using GitHub's repository template functionality
2. Update the README.md and .firebaserc with the respective values.
3. Configure your Firebase, Octopus Deploy, and Twilio accounts
4. Create your Firebase project
5. Deploy the functions to Firebase
6. Configure your Octopus Deploy subscriptions
7. Configure your Twilio phone number webhook

Set up

Requirements

• Node.js
• A Twilio account - sign up
• A Firebase account - sign up
• The Firebase CLI
• An Octopus Deploy instance - sign up

Application Settings

You will need the following values to configure Octwilio to work with your Firebase, Octopus Deploy, and Twilio accounts.

Twilio Account Settings

Config Value	Description
Account Sid	Your primary Twilio account identifier - find this in the Console.
Auth Token	Used to authenticate - just like the above, you'll find this here.
Phone number	A Twilio phone number in E.164 format - you can get one here

Octopus API Key

Config Value	Description
API Key	An [API key](API key.) for authenticating requests to Octopus Deploy

Firebase Settings

Config Value	Description
Project ID	The ID of your project (not always the same as the name) - find this in the Console
CLI CI Token	(Optional) A CI token to authenticate requests from the Firebase CLI.

Local development

After the above requirements have been met:

1. Clone this repository and cd into it

git clone git@github.com:youraccount/octwilio.git
cd octwilio

2. Configure your project with the Firebase CLI

After creating your Firebase project, replace octwilio in .firebaserc with your project's ID.

You also need to create a Firestore database for the approval notifications.

Create a CI token for the CLI.

3. Update the following commands with your values and run them with the Firebase CLI.

firebase functions:config:set octwilio.octopus.token="Use any token / passphrase you want here but keep it secure"
firebase functions:config:set octwilio.octopus.apikey="API-MYSECRETISSAFE"
firebase functions:config:set octwilio.twilio.account_sid="The account ID from Twilio"
firebase functions:config:set octwilio.twilio.auth_token="The auth token from Twilio"
firebase functions:config:set octwilio.twilio.approval.from_number="+15555555555 - the Twilio number to send approval alerts from"
firebase functions:config:set octwilio.twilio.approval.to_number="+15555555555 - the number to send approval alerts to"
firebase functions:config:set octwilio.twilio.deployment.from_number="+15555555555 - the Twilio number to send deployment alerts from"
firebase functions:config:set octwilio.twilio.deployment.to_number="+15555555555 - the number to send deployment alerts to"

4. Install dependencies

cd functions
npm install

5. Deploy the functions to your Firebase project

npm run deploy

There is a deploy workflow that will deploy your functions when changes are pushed to master. Add a secret named FIREBASE_TOKEN with your Firebase CI token for the deploy action to work. You can delete the file if you do not want to use it.

6. Update Twilio number with processMessage URL

Navigate to your Twilio number that will accept messages from the user.

Update the A Message Comes In webhook endpoint to the processMessage URL. It will look something like https://us-central1-octwilio.cloudfunctions.net/processMessage.

7. Create Octopus subscriptions

In your Octopus instance, create a subscription for Manual intervention interruption raised events that posts to your approvalRaised function URL. See more details in Building Octwilio #2

You can create a subscription for deployment events if you want to receive alerts for those.

8. Create Octopus projects (if none exist)

If you're new to Octopus, follow our Getting Started guide or webinar to set up some environment and projects. For testing, you can set up projects with simple script steps or just a manual intervention.

Resources

• GitHub's repository template functionality
• Building Octwilio

License

MIT

Disclaimer

No warranty expressed or implied. Software is as is.