Introduction
This guide is designed to get you started on drush.io. In particular, we’ll cover
- Account setup and authorization
- Project and job management,
- Job execution
All you need before you begin is a drush.io account. We’re still in private beta, but you can sign up for the beta waitlist here.
Setting Up Credentials
In order for drush.io to execute workflow operations on your behalf, you need to provide a valid Pantheon machine token.
-
First, log in to you drush.io account. By default, you land on the
Projects
tab of your account dashboard. Navigate to theCredentials
tab. -
Click the
Add Credential
button. A dialog will appear where you can enter a credential name likeWork Pantheon Account
-
Click the
Create Machine Token and Paste Here
button. This will open a small window on the Pantheon machine token generation page (you may be prompted to log in to Pantheon). -
In the Pantheon dashboard pop-up, click the
Generate Token
button. Once generated, copy the machine token to your clipboard. -
Close the pop-up window and paste the contents of your clipboard into the
Pantheon Machine Token
field in the dialogue. -
Click the
Add Credential
button in the dialog. -
Once added, you’ll see a confirmation dialog, which displays an SSH public key. In the background, drush.io will add the corresponding private key to your Pantheon account. This key pair is used to run
drush
andwp-cli
commands invoked in your jobs. -
You may optionally add this public key to other services (like Github or Bitbucket) for deeper integration into your operations stack.
With your credential set up, you’re ready to create a project!
Creating Projects
Projects are a way to collaborate with your colleagues on a set of jobs specific to your organization.
-
First, navigate to your account dashboard. The
Projects
tab should be the default tab you land on. -
Click the
Create Project
button. A dialog will appear where you can enter a project name. You may wish to use your organization’s name for simplicity. -
As you type your project name, you’ll see a suggested machine name generated for you. This machine name is globally unique across the platform and can be used to identify your project using the drush.io API. You may modify this value if you don’t like the generated value.
-
Click the
Save
button in the dialog and your project will be created.
With your project set up, you can start writing jobs!
Creating Jobs
A job is a set of instructions that encapsulate an operation you may want to run repeatedly.
As an example, imagine a Refresh test environment
job that clones content and files from live
to test
, clears caches, and triggers a short-lived backup.
-
Navigate to the
Projects
tab of your account dashboard and click into the project you want this job to live under. -
By default, you’ll be taken to the
Job Runs
tab of your project dashboard. If you’ve never run a job before, the list of runs will be empty. -
Navigate to the
Jobs
tab and click theCreate Job
button. -
A dialog will appear. At the top is a job name field where you can enter a descriptive name. In the example job above, you would enter
Refresh Test Environment
. -
Below the job name field are two sections. On the left is a text area where you will compose your job script. To the right is a preview area that displays job run progress and output when a preview run is triggered.
- In the text area to the left, enter the commands that make up your job. For the example job above, it might look something like this:
terminus env:clone-content my-site.live test --yes terminus env:clear-cache my-site.test terminus backup:create my-site.test --keep-for=1
For details on the runtime environment and script syntax, see Jobs and the Runtime.
- Click the
Save
button in the job create dialog to complete the process.
Now that you have a job, you’re ready to run it!
Queueing Jobs
On its own, a job is just a set of instructions. You can put these instructions in motion by creating a job run. There are several ways to queue a job for execution. We’ll cover two mechanisms here.
Via the job edit dialogue
-
Navigate to the “Jobs” tab in the project dashboard where your job lives.
-
Click the job you wish to run. This will open a job edit dialogue, similar to the job create dialogue.
-
At the bottom of the dialogue, next to the
Save
button is aSave and Preview
button. Click this to queue the job. -
Once clicked, the preview area in the right-hand side of the dialogue will activate. The preview area will cycle through runtime acquisition and job run phases.
-
Once the job run has completed, the log output from the job will be displayed in the preview area. If any changes to the job need to be made, you can do so in the script area to the left.
Via the job action menu
-
Navigate to the “Jobs” tab in the project dashboard where your job lives.
-
Click the action menu icon to the right of the job you wish to run. In the drop down menu, click
Queue Job
. -
A notice will appear indicating the job was successfully queued to run.
-
Navigate to the
Job Runs
tab, where a new job run should appear in aqueued
orrunning
state. Once the job has completed, you can view the job’s log output by clicking theView Log
item in the action menu to the right of the run.
You’ve now successfully created a job and run it on the platform! Time to invite your teammates.
Inviting Teammates
Creating and running DevOps workflows right in the browser is just the beginning. Imagine what’s possible when you invite the rest of your team!
-
Open up drush.io to the project dashboard for a project that you created or are an administrator of.
-
Navigate to the
Team
tab and click theInvite Teammate
button. -
Enter your colleague’s e-mail address in the invitation dialogue and click
Invite
. -
Your colleague will receive a welcome e-mail, indicating that they’ve been invited to your drush.io project. Let them know to open the e-mail and activate their account.
-
Until they activate their account, they’ll show up in your team as as generic
drush.io user
. -
By default, teammates are added as basic members, but you can grant teammates the administrator role using the action menu to the right of the user on the
Team
tab. -
Be a dear and send them this documentation!
Now you’re cookin’ with grease! Time to dive deeper into jobs and the runtime.