Skip to content

Getting Started

Jump to bottom
perpil edited this page Apr 16, 2024 · 86 revisions

Installation

  1. Install Tampermonkey if you don't already have it.
  2. If you're using Chrome, follow these additional instructions to configure Tampermonkey.
  3. Install Speedrun
  4. Reload this page

Play with a live demo

Since Speedrun is different than anything out there, to wrap your head around its capabilities, try the live demo. You don't even need an AWS account, it uses ours!

Learn the basics

Turn on Speedrun for your Repository

image

Speedrun is enabled per repository. Enable it on repositories you trust by using the sword slider.

Using a template

Each Speedrun block starts with a template which tells Speedrun what to do. The simplest template is the #copy template which copies something to the clipboard, but there are others including ones to federate into the AWS console, invoke Lambdas and Step Functions. To get Speedrun to find and wire up your block, wrap your content with code fences (```), put the #template you want to use on a new line and enter any content below that.

Tip

Click the Code tab to see the underlying Markdown for an entry. Click the copy icon to copy the underlying Markdown to the clipboard.

This will use the #copy template to copy something to the clipboard. Click the ${\textsf{\color{lime}green}}$ Copy button to invoke it.

#copy
This was copied by ${user}

Read more about templates, the different template types, built-in templates for running things like CloudWatch queries and how to build your own here.

Prompting for inputs

To prompt the user, wrap the prompt name with 3 tildes (~~~) on each side. Speedrun will replace it with what the user enters.

#copy
This is ${user}'s favorite color: ~~~Favorite Color~~~

Further you can use prompts to set variables. The syntax is: ~~~variable=Prompt Text~~~ You can reference a variable before and after it is defined.

#copy
This is ${user}'s favorite loud color ${color.toUpperCase()}
This is ${user}'s favorite color: ~~~color=Favorite Color~~~

Read more about prompts, changing the prompt type, adding validation, labels, default values and transforming inputs here.

Running JavaScript

To use JavaScript wrap content with ${}.

Tip

Click the Debug tab to see the variables Speedrun exposes for the current page context.

Here ${user.toUpperCase()} is used to get the current GitHub username in uppercase.

#copy
This is ${user.toUpperCase()}'s favorite color: ~~~Favorite Color~~~

Read more about using JavaScript, the built-in helper functions and defining your own functions here.

Learning the User Interface

Find out how to use the toolbar and the interface here: User Interface Documentation

Configuration

Speedrun configuration is used to define what appears in the toolbar and to set the corresponding context for the page. You can set the optional AWS account and role used during federation and any configuration you want associated with your environments, stages or blocks (i.e. the CloudWatch log group name). You can see the current context variables by clicking the Debug tab of any Speedrun block. To configure all the AWS accounts and configuration your team uses read configuring Speedrun for your environment

Getting AWS Credentials

Hold on speedy, first you need to configure your AWS accounts and roles. For a better user experience, use the Speedrun credentials broker described below. If you want to use Identity Center; follow the Identity Center cookbook If you want to use Granted; follow the Granted cookbook.

Create Speedrun Roles

Follow this wiki to create the necessary Speedrun roles and to register your AWS accounts

Install srinit

srinit is a command line tool that authenticates you with GitHub so you can assume the Speedrun roles you have access to

#copy
python3 -m pip install --extra-index-url https://speedrun.nobackspacecrew.com/packages srinit

Now run srinit to authenticate so you can run AWS CLI commands.

Note

srinit needs to be run once every 24 hours.

#copy
srinit

Using Credentials

If you've added your account and role to the settings, you can now use them to federate into the AWS console using the #federate template.

#federate

If you have the AWS CLI installed, you can run commands with credentials using the #copy.withCreds template like this.

#copy.withCreds
aws sts get-caller-identity

Next Steps

  1. Join the Discord for help
  2. Read the cookbook for some examples of configuration
  3. Read this blog and interact with it here.
  4. Learn how it works below

How it works

Speedrun takes a template that defines what you want it to do, sets the variables from the context set by the toolbar and evaluates the JavaScript locally in the browser. It can use any of the following to do what you need to do.

  1. Markdown content referenced by ${content} in templates is what you put in your code fences. It can be any text content including things like json, a url, a command line or JavaScript code.
  2. Prompts prompt the user for input. By default, they are set to what was entered last time the user was prompted for the same thing.
  3. Credentials Speedrun operates as a credentials broker, if the authenticated GitHub user is authorized to assume the role (specified by the role variable) in the account (specified by the account variable), it can vend credentials to federate into the AWS Console or provide credentials for the command line.
  4. Configuration defines things like what AWS accounts and roles to use, what your services are called and any configuration you want to associate with your services such as the log groups or the stage.
  5. JavaScript to manipulate inputs, reference configuration and set default values.

Speedrun does the following when you load a markdown page.

  1. Finds all the configuration for current page and uses it to build the toolbar
  2. Looks for code fences that use a defined template, adds buttons to them and renders a preview.
  3. When the do it button is clicked; prompts for any inputs, resolve any variables, and run all JavaScript code to process the template.
  4. Depending on the template type, copy the result to the clipboard, open a link, federate into the AWS Console, invoke a lambda or step function or download the result as a file.
Clone this wiki locally