We're going to go through creating a step (properly) and sharing it with the Bitrise community. Tutorial based on a real step created and written by Sébastien Pousse.
Guest blog post by Sébastien Pousse, the original appeared on Developers @ Yellow Pages in French.
Sébastien works for PagesJaunes (French Yellow Pages) as head of innovation and mobile strategy and he likes sports, especially climbing, squash, mountain biking and running.
Summary
Bitrise is a solution that allows you to industrialize your mobile compilations (iOS, Android, Xamarin, ReactNative, Ionic etc.) by making dedicated virtual machines available for a defined period of time.
These virtual machines are launched on demand following trigger events (activity on your source code repositories for example) and execute a workflow containing a set of steps.
A step is a cogwheel of your workflow, that will run and perform a specific task.
Bitrise offers a catalogue of steps already written:
The objective of this tutorial
In this tutorial I'll assist you in the creation of a step, explaining all the essential steps until the submission of the step to the Bitrise team to appear in the catalogue above.
Customer in the command line
Bitrise is a SAAS solution but it is still possible to work locally with it. For that, we will first install a Bitrise client in CLI with homebrew .
Setup
We will do updates with a bitrise setup, which will take care of updating the kernel tools like envman, stepman. It'll also install Bitrise plugins, in particular, the one for steps that is important for us.
Initialization of the step
Let's get down to business. We will start with an actual case: at the moment I need to be able to upload a build to wetransfer to send it to a third party.
We will design a step which uploads a file on wetransfer.
The small novelty is that since version 1.6 of the Bitrise client in CLI, the creation of a step is simplified. Go to a working directory and run the command bitrise :step create
Answer all the questions above.
Choose a category. I chose utility.
In my case, I chose to do the step in nodejs and the script will be launched in bash so 1) it is.
I've decided to store the step on GitHub. The repository of my step is created, as well as all the necessary files.
Let's check that the test workflow starts all right...
Achtung!
There are some basic rules to know before you start:
- Every input, output and parameter in any step is an Environment Variable
- The value of an Environment Variable can only be a String
- If you create an environment variable in a child process, it will not be visible from the parent process
I repeat these here because these caused me some trouble 🙂 (Read more about these concepts here.)
Workflows
bitrise.yml
This file is actually the main configuration file. It will allow you to create one or more workflow(s) and define one or more step(s) to execute. This is your scheduler, which you will find in the cloud. This file is in YAML format.
Let's look at some elements of the file.
Environment variables
We have a series of variables defined globally to our application. These variables are reusable from anywhere thereafter.
For the variable MY_STEPLIB_REPO_FORK_GIT_URL, the bitrise-steplib project will have to be forked. Indeed it is in this project that our step will be placed in the end.
The test workflow
The test workflow contains a step with a bash script that will display the environment variable declared above. Nothing really exciting at the moment.
The test workflow will later allow you to test your step in the command line and also on Bitrise.
Specification
Back to the step. I will declare all the parameters I need for uploading to wetransfer. Here's what I need:
- The sender's email address
- The email address of the recipient(s)
- A short message to accompany the link
- The files to send to wetransfer
It's as simple as that. Once the problem is posed, here is how to solve it.
Production
The description of the step (step.yml)
You can find the source here. In this file, we will describe the operation of the step and set all the parameters necessary for its proper functioning.
I will not go into all the details, I'll only deal with the input variables which are the most interesting in our case:
This will materialize as follows:
The is_expand statement is used to directly expand the description field
The is_required statement specifies that the variable is required.
And so on for all the expected parameters. There is also a possibility of making lists.
For example, for the debug mode I just want to make an enum {yes, no}.
Fill in the form ...
Execution of the step (step.sh)
You can find the source here. This file will be executed each time the step is launched.
Following feedback from Bitrise, I had to make some changes. The most important thing is not to change the working directory. This is advocated by Bitrise.
In the end, the step.sh will launch my nodejs script with the set of parameters that have been entered in the configuration interface of the step.
The main script (upload.js)
(Source file.) I will not go into the details of the script, it is not really the object of the tutorial, just understand that as a default, you can develop steps in bash and go languages. If you'd like to use any other language, you can, but you have to check if the interpreter belonging to the given language is pre-installed on the Bitrise virtual machines or not. If they are not, then choosing bash, you have to install the chosen interpreter from the bash script and also run your choice of script from there.
The transfer.js script takes arguments on the standard input that match the expected parameters and are provided by the step.
What is important in particular is to be able to notify the user quickly enough when the step does not have all the required parameters. I did not go very far with this in this first version, especially since we specify values as is_required in the step.yml.
But for example, I could verify that the given directory exists and contains many files, and if it is not the case I could directly send an error message. This saves time and interrupts the step directly.
The audit of the step
Once our step finished running, we will check that everything is ok by launching the audit of our step via the command:
A priori it is a format validation of the step.yml which is tested here. If all went well we'll see this:
Forking the bitrise-steplib project
The final goal is to put this step in the project bitrise-steplib and make a PR so that Bitrise can validate the step (or not).
Fork the project: https://github.com/bitrise-io/bitrise-steplib
Then fill in the url of the fork in the file bitrise.yml
- MY_STEPLIB_REPO_FORK_GIT_URL:https://github.com/kawaiseb/bitrise-steplib
Once this is done, you can share his step.
Share the step
Start with the command:
bitrise-step-wetransfer [master] bitrise run share-this-step
This command will prepare the PR for the stepLib. Then what only remains is to submit it to Bitrise.
Well... I will not hide that I had to go back to it 3 times. 🙂
Before the step was accepted, here are the main reasons for the refusal by the Bitrise team:
- Cleanness of the step: I left a lot of unnecessary things in the code
- Bad compliance with the guidelines on variable names. The input variables must be in lower case, the output variables in upper case, for example
- Then in my step, I made a change in a directory which could actually have an impact for a person who executed my step in his workflow
Conclusion
Well, this is it, now you can create and share a step. The nice thing is that you can use the technology of your choice, we could have done a script in Ruby or php, in short: I did not see any limits. The only limitation is to preinstall the necessary dependencies.
Feel free to write me comments, ask questions or tell me if some points are not clear enough :)
Links
You can find the source files of the step in question here: https://github.com/kawaiseb/bitrise-step-wetransfer
The bitrise-steplib Bitrise project that will need to be forked: https://github.com/bitrise-io/bitrise-steplib
The lib nodejs to use the wetransfer API: https://www.npmjs.com/package/wetransfert
The discussion forum (they are very responsive):
https://discuss.bitrise.io/
English version by Anna Bátki.