What are Bitrise Steps?
Bitrise has over 330 Steps for all mobile platforms and all of them are open-source. A Bitrise Step is a specific task: for example, the Git Clone Step clones your Git repository at the start of a build while the Google Play Deploy Step can deploy your finished app to the Play Store.
Bitrise Steps are written in either bash or Go, but they can be written in other languages too, if they can be started by a bash command.
E.g: You can write your Step in ruby, but you have to select bash when you create the Step with the CLI. Then, in the step.sh file you'll need to start your ruby code by a bash command. Steps are contained in your own Git repository, which includes the code and the step.yml file that defines the configuration of the Step.
In this guide, I’ll walk you through the most important aspects of creating and submitting a new integration Step to install and run the Appium server, to be able to run your automated tests on Bitrise.
Later on, I’m planning to share the Step on Bitrise for other Bitrise users as well, so others could use my Step in their Bitrise app too.
Before you get started
You will need to install the Bitrise CLI, set it up, and make sure the Step plugin is installed and updated to the latest version. You can use curl or Homebrew and you can check the latest release of the Bitrise CLI on its releases page.
1. I will use Homebrew in this tutorial to install Bitrise CLI:
2. Installing the Bitrise Step plugin
The Step plugin is included in the bitrise CLI by default. To ensure that you have the latest version of Bitrise CLI run the following command: bitrise update.
We are ready now to start creating our Bitrise Step.
Creating the Step
3. Open a command-line interface, such as the Terminal app on macOS.
4. Create the Step with the Bitrise Step plugin.
5. You’ll need to set different values, such as:
- Name of the Step’s author
- Step’s name (title)
- Summary
- Description
- Category
- Toolkit (language)
- Source code hosting
As displayed in the following screenshots:
TIP:
If you select go for the language for the Step development, then your Step will be created in the default Go directory on your computer.
For example: /Users/YOUR_USER/Develop/go/src/
This means that even if I run the CLI bitrise :step create on the desktop, the CLI will create all of my new Steps written in go under the /Users/USERNAME/Develop/go/src/ directory.
You will notice that you have different files, such as the step.yml file. This is the Step interface definition containing the dependencies, Step inputs and Step outputs, as well as other Step properties. It also points to the location of the Step’s source code. Every Step must have one. Besides the step.yml file you can also have step.sh/main.go, bitrise.yml, and README.md depending on your Bitrise Step.
If everything goes well, the plugin will initialize a git repository in the current directory.
Congratulations! The Step is ready and we will start adding our own implementation before deploying it.
TIP
Because we used the Step plugin to create a new Step, all the required properties will have a value assigned. You can also change these at any time, so don’t worry if the title you set during the initial process does not conform to this guideline.
You can now open the step.yml file in your preferred editor and start modifying any inputs or values you entered before.
For example, you can specify the platform for this Step by selecting iOS, Android, and React Native
If your Step is for a specific platform, then it will be shown for that platform filter in the Workflow Editor when you share your Step with other users on Bitrise.
But if the Step has no platform specified (e.g: Slack) then it will be listed for all the platforms. You also can configure the Step inputs, including the sensitive inputs or the Env Vars.
For the Appium Server Step, I will change the input to be the Appium version to be able to install a specific version and will add a default value for the Step (ex: v1.21.0)
If your Step provides the output, you can also configure it with the Step outputs. Steps can generate outputs which then can be used in other Steps as inputs. That means that if a Step generates an artifact, the path to that artifact can be the input of another Step in the build.
But in my case, because I’m installing and running the Appium server only, I will remove it from the step.yml file. After that in the step.sh file, I will add the command to install and run the Appium server as a backend service without GUI.
NOTE:
You will notice that I’m using the appium_version Environment Variable from the step.yml file in this script. Now it’s time to create a new pull request to the StepLib repository, more details can be found in the sharing step guideline. Push your repository to GitHub and create the release tag to be ready to open your pull request.
NOTE:
The release tag should be the same number in the bitrise.yml, file for example “0.0.2”
You also need to change the MY_STEP_REPO_FORK_GIT_URL to your steplib forked repo.
Before sharing your Step, you can test it to make sure that everything works well.
Testing the Step
There are two ways to test the Step:
First option: Testing your Step locally
1. Open a command-line interface, such as the Terminal app for macOS.
2. Go to your Step’s directory
3. Run the automatically generated Workflow.
And that’s it, Bitrise will run the test for you and the logs will tell you if everything worked as intended.
Second option: Testing your Step on Bitrise before sharing it
1. Fork the Bitrise StepLib repository.
2. Add your Step’s step.yml to the forked StepLib repository.
3. In the bitrise.yml file of your testing app, set the forked StepLib repository as the value for default_step_lib_source. If the Step reference does not specify a direct source, this value will be used.
4. Add the Step to the Workflow: use the Step ID and, optionally, a version number.
5. Run a build with bitrise run workflow_ID to check if your Step worked successfully.
You can also test your Step on Bitrise by a Git URL by taking the following steps:
- Create a new App on Bitrise for your step
- We suggest using the https Git URL as the Step's repository is public.
- Add your Step to a test Workflow by adding its https Git URL and specifying the branch to test ( e.g: master ) like the following format:
- Make sure all the necessary inputs and artifacts are available for your Step before it runs.
You can find more information about testing and versioning your Steps here.
Auditing the Step
To Audit the Step, you can run the following command-line:
And the results should look like this:
Sharing the Step
There are two ways to share a Step:
You should fork Bitrise StepLib first. Then you can add the Step icon (especially if you are submitting a Verified step).
NOTE:
You should add the .svg file into your StepLib repo at: STEPLIB_ROOT/steps/YOUR_STEP_ID/assets/icon.svg.
You can do it manually, using the bitrise share command with the following steps:
Or, if you created the Step with the Step plugin like in our tutorial, you can run the share-this-step Workflow in your Step’s directory like this:
bitrise run share-this-step
Finally, you can create your pull request. You also need to sign the Bitrise Contributor License Agreement before we can accept your contribution.
Once you sign the Agreement, the Bitrise team will review your pull request and accept or ask you to make changes if there’s an issue. After the PR is merged successfully, you can start using your Step in Bitrise Workflow, run the build, and check the results.
And the Step will be listed in the Bitrise Step Library as well.
TIP:
You can always improve or update the Step but always make sure that you are using new versions.
In case you’d like your newly published Step to become a Verified Step, you can learn more about the process here. You can also apply to become a Technology Partner, or simply get in touch with us at [email protected].
Congratulations 🎉, you created your first open-source Bitrise Integration Step 🚀 and we hope that there are many more to come. 💜
Future Reading
For detailed information on how Steps work, see the following guides:
- Workflows in YAML
- Basics of bitrise.yml
- Steps in YAML
- Step inputs
- Step outputs
- Step properties
- Testing and versioning your Steps
- How to contribute to Bitrise
- Step Development Guideline
- Abandoned Step policy
- Verified Steps
