How to take advantage of Dynamic Workflows using Codemagic API
You can now configure your builds using environment variables and software versions dynamically using Codemagic API. If you have multiple similar workflows for the same project, you can now combine them to one and create parametrized API calls. In this way, you can run your workflows without having to change the setting in the UI or codemagic.yaml. This can be a quite useful feature for white-labeled apps.
In this article, I will show you how to make calls to Codemagic REST API for starting the build, getting updated status information & canceling the build.
First of all, let’s go through the features of the API.
Overview
The Codemagic API can be accessed using the URL: https://api.codemagic.io
All data is sent and received in the JSON format.
Authentication
While making any calls to the Codemagic REST API, an access token must be included as an HTTP header for the call to be successful.
You can get the access token from the Codemagic UI by going to User Settings -> Integrations -> Codemagic API -> Show.
Retrieve applications
You can get information about all the applications present on Codemagic by sending a GET request to the following endpoint:
GET /appsSome of the important parameters that you can retrieve from the response are App IDs, Workflow IDs, Branches, etc.
An example of curl request for retrieving applications is as follows:
curl -H "Content-Type: application/json" -H "x-auth-token: <API Token>" --request GET https://api.codemagic.io/appsReplace the angle bracket with its appropriate values.
Start a new build
For starting a new build using the Codemagic API, you have to send a POST request to the following endpoint:
POST /buildsThe required parameters are appId, workflowId & branch, and there is an optional parameter environment for passing environment variables and software versions.
You can pass which version of Flutter/ Xcode/ CocoaPods to use for the build and also any environment variables as a key-value pair.
So, if you have multiple workflows having small differences, like in the software versions or separate git branches, then you can merge them and use Codemagic API to dynamically change their values.
The variables passed via API have higher priority and will override the values defined in the UI.
For more information refer to the Official Docs.
An example of curl request for starting a new build is as follows:
curl -H "Content-Type: application/json" -H "x-auth-token: <API Token>" --data '{"appId": "<app_id>","workflowId": "<workflow_id>","branch": "<git_branch_name>"}' https://api.codemagic.io/buildsReplace the angle brackets with their appropriate values.
Get build status
While a build is running on Codemagic CI/CD, you can check its status using the Codemagic API by sending a GET request to the following endpoint:
GET /builds/:idHere, replace the
:idwith the build id returned as a response of the POST request.
An example of curl request for getting build status is as follows:
curl -H "Content-Type: application/json" -H "x-auth-token: <API Token>" --request GET https://api.codemagic.io/builds/<build_id>Replace the angle brackets with their appropriate values.
Cancel a build
If you want to cancel a build that is currently running on Codemagic CI/CD, you can send a POST request to the following endpoint:
POST /builds/:id/cancelReplace the
:idwith the build id returned as a response of the POST request while starting the build.
An example of curl request for canceling a build is as follows:
curl -H "Content-Type: application/json" -H "x-auth-token: <API Token>" --request POST https://api.codemagic.io/builds/<build_id>/cancelReplace the angle brackets with their appropriate values.
Use cases
You can use Codemagic REST API for better integration with other tools so that you can take advantage of the Dynamic Workflows.
As a fun project, let’s create a Flutter app using Codemagic API.
The app will be pretty simple, having features to:
- Start Build with supplied software versions
- Get Build Status while it is running
- Cancel Build that is running on Codemagic CI/CD
Let’s get started building the app.
App screenshots
The final app design will be like this:
Getting started
Create a new Flutter project using the command:
flutter create codemagic_apiThe only plugin that you will require for this project is:
- Dio (A powerful HTTP client for Dart)
Open the project in your favorite IDE and import the dio package using pubspec.yaml.
Initializing Dio
You can initialize dio with some base options like URL, Headers, etc. Here, I have defined a connectTimeout & receiveTimeout in milliseconds.
I have stored the API token in a Map and accessing it form there.
Start build
As I have described earlier, for starting a build you have to send a POST request to the API endpoint /builds.
For this, you can use the dio post() method with the endpoint and proper parameters.
NOTE: Here, I have stored the values in a Map and accessing them from there.
From the response received from the POST request, you can retrieve the Build ID which we will require later for getting the build status and for canceling the build.
Build status
For getting the build status, you have to send a GET request to the API endpoint /builds/:id.
You have to use the dio get() method with the proper endpoint.
Now, you can define a stream for this, which will run it infinitely and get the updated build status until the build finishes or canceled.
Cancel build
If you want to cancel a build, you have to perform a dio post() method call using the endpoint /builds/:id/cancel.
The UI of the app will be quite simple, containing mainly TextFormField for taking user inputs and Button for starting/canceling a build.
The TextFormField design will be like this:
Code for each TextFormField is as follows:
If there is no build currently running then a RaisedButton will be displayed, which can be used for starting a new build.
When there is a build running then the build status along with a CANCEL button will be displayed. The UI design will be as follows:
The whole app code is available on GitHub here:
Conclusion
I hope this article will help you to get started with Codemagic REST API and take advantage of the Dynamic Workflows for building your apps.
Codemagic API Docs: https://docs.codemagic.io/rest-api/overview
Originally published at https://blog.codemagic.io/dynamic-workflows-with-codemagic-api
Check out my other articles
If you want to support me and want me to continue writing Flutter articles and building some interesting Flutter projects, please contribute to my Patreon page below:
You can follow me on Twitter and find some of my projects on GitHub. Also, don’t forget to checkout my Website. Thank you for reading, if you enjoyed the article make sure to show me some love by hitting that clap (👏) button!
Happy coding…
Souvik Biswas
