CI/CD Setup

welcome! this guide will help you set up automatic deployment for your back4app project when you're done, pushing code to github will automatically update your back4app app no prior experience with github actions is required table of contents /#what does this do /#what youll need /#step 1 clone your repository /#step 2 set up back4app cli and project structure /#step 3 find your back4app app ids /#step 4 edit the workflow file /#step 5 add your secrets to github /#step 6 create your branches /#step 7 deploy /#how to use it daily /#troubleshooting /#glossary ⚠️⚠️⚠️ very important ⚠️⚠️⚠️ though flexible and configurable, this continuous integration and continuous delivery (ci/cd) project is aimed at running back4app backend as a service (baas) projects only you might change it and adapt it to your specific needs, using this as a template, but have in mind that it does many checkings on back4app's baas folders, files and settings, so ensure to adapt accordingly a few of those checks include \ a configured back4app backend as a service project, which you can obtain by using the back4app command line interface tool (cli) https //www back4app com/docs/local development/parse cli what does this do? this workflow automatically uploads your code to back4app whenever you push changes to github here's how it works ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ you push code │ →→→ │ github actions │ →→→ │ back4app app │ │ to github │ │ runs workflow │ │ is updated │ └─────────────────┘ └─────────────────┘ └─────────────────┘ two distinct branches when you push to your code goes to development branch development back4app app (for testing) main branch production back4app app (for real users) this lets you test changes safely before releasing them to your users ⚠️⚠️⚠️ tip in order for this flow to work as it is, the branches must be named like above ⚠️⚠️⚠️ what you'll need before starting, make sure you have a github account with a repository created for your app two branches named exactly development and main a back4app account two back4app apps created one for development (development and testing) one for production (live/real users) your project code in a github repository a code editor (like vs code, cursor, or even github's web editor) ⚠️ important the branch names must be exactly development and main for this workflow to work as is! don't have two back4app apps yet? you'll need to create them first log into back4app click the "new app" button on the top right side create your first app and name it something like "developmentapp" create your second app and name it something like "productionapp" 💡 tip keep the names simple so you can tell them apart easily step 1 clone your repository before you can add files to your project, you need to download (clone) your github repository to your computer 1 1 find your repository url go to your repository on github open your web browser go to github com/your username/your repo name click the green "code" button it's near the top right of the file list copy the url make sure "https" is selected (it's the default) click the 📋 copy button next to the url the url looks like https //github com/your username/your repo name git 1 2 clone the repository to your computer 🍎 macos open terminal press cmd + space to open spotlight type "terminal" press enter navigate to where you want to store your project \# go to your documents folder (or wherever you want to work) cd /documents clone the repository \# replace the url with your actual repository url git clone https //github com/your username/your repo name git enter the project folder \# replace your repo name with your actual repository name cd your repo name 🐧 linux open your terminal navigate to where you want to store your project \# go to your home folder (or wherever you want to work) cd clone the repository \# replace the url with your actual repository url git clone https //github com/your username/your repo name git enter the project folder \# replace your repo name with your actual repository name cd your repo name 🪟 windows (powershell) open powershell press win + x select "windows powershell" navigate to where you want to store your project \# go to your documents folder (or wherever you want to work) cd \documents clone the repository \# replace the url with your actual repository url git clone https //github com/your username/your repo name git enter the project folder \# replace your repo name with your actual repository name cd your repo name 🪟 windows (command prompt) open command prompt press win + r type "cmd" press enter navigate to where you want to store your project rem go to your documents folder (or wherever you want) cd %userprofile%\documents clone the repository rem replace the url with your actual repository url git clone https //github com/your username/your repo name git enter the project folder rem replace your repo name with your actual repository name cd your repo name 🪟 windows (git bash) if you installed git for windows, you have git bash which works like macos/linux open git bash right click on your desktop or in a folder select "git bash here" navigate to where you want to store your project \# go to your documents folder (or wherever you want) cd /documents clone the repository \# replace the url with your actual repository url git clone https //github com/your username/your repo name git enter the project folder \# replace your repo name with your actual repository name cd your repo name 1 3 verify the clone worked after cloning, you should see your project files run this command to check ls la on windows command prompt, use dir you should see your project files listed, including any existing files from your repository 1 4 open the project in your code editor 📝 vs code or cursor option a from the terminal \# opens vs code in current folder code \# opens cursor in current folder cursor option b from the application open vs code or cursor click file → open folder navigate to your project folder click open 📝 other editors open your code editor look for file → open or file → open folder navigate to the folder where you cloned your repository open it ✅ success! you now have a local copy of your repository any changes you make here can be pushed back to github step 2 set up back4app cli and project structure before adding the workflow file, you need to set up the back4app command line interface (cli) and connect it to your back4app apps this will create the necessary cloud folder structure in your project 📖 official documentation https //www back4app com/docs/local development/parse cli 2 1 install the back4app cli the cli lets you manage your back4app apps from your terminal 🍎 macos prerequisites you need python installed on your mac (it usually comes pre installed) open terminal (press cmd + space , type "terminal", press enter) run the installation command curl https //raw\ githubusercontent com/back4app/parse cli/back4app/installer sh | sudo /bin/bash enter your password when prompted (you won't see characters as you type that's normal) verify the installation b4a version you should see a version number 🐧 linux prerequisites you need python installed open your terminal run the installation command curl https //raw\ githubusercontent com/back4app/parse cli/back4app/installer sh | sudo /bin/bash enter your password when prompted verify the installation b4a version 🪟 windows download the cli executable go to https //github com/back4app/parse cli/releases download the file named b4a exe move the file to make it accessible globally move b4a exe to c \windows\system32\ (you may need administrator permission) verify the installation open command prompt or powershell run b4a version 2 2 get your back4app account key you need an account key to connect the cli to your back4app account log into back4app at back4app com click on your profile icon (top right corner of the dashboard) look for "account keys" in the menu give your account key a name and click the "+" button on the right side a new account key will be created copy your new key immediately ⚠️ important keep your account key secret! never share it or commit it to your repository write it down somewhere safe my account key 2 3 configure the cli with your account key now connect the cli to your back4app account open your terminal and navigate to your project folder cd /path/to/your project run the configuration command b4a configure accountkey paste your account key when prompted and press enter 💡 note if you've configured a key before and need to update it, use b4a configure accountkey d 2 4 link your back4app app to your local project this step creates the back4app cloud code structure inside your cloned repository ⚠️ important run this command inside your cloned repository folder (from step 1) this ensures the back4app files are added to your git tracked project! make sure you're in your cloned repository folder \# navigate to your cloned repo (the folder from step 1) cd /documents/your repo name \# verify you're in the right place (should show git folder) ls la run the new app command b4a new when prompted, choose to link an existing app you'll see options like (n)ew or (e)xisting type e and press enter to link an existing app select your development app from the list use the project's number to choose press enter to select when asked for "directory name " just press enter to accept the default (uses your app name) or type a simple name like app and press enter the cli will create a subfolder with this name when asked about blank project please type "(b)lank" if you wish to setup a blank project, otherwise press enter just press enter to get the default template with sample files the cli creates the files in a subfolder your project/ ← your cloned repo ├── git/ ← already exists from step 1 └── myapp/ ← subfolder created by cli (name may vary) ├── cloud/ │ └── main js ├── public/ │ └── index html ├── parse local └── parse project 2 4 1 move files to repository root the workflow expects the cloud folder to be in the root of your repository, not in a subfolder follow these steps step a first, find out what the subfolder is called ls you'll see something like myapp (the name will be whatever your back4app app is called) step b run these 4 commands one by one, replacing myapp with the name you saw above 🍎 macos / 🐧 linux / git bash mv myapp/ mv myapp/ parse local mv myapp/ parse project rmdir myapp 🪟 windows (powershell) move item path "myapp\\ " destination " " move item path "myapp\\ parse local" destination " " move item path "myapp\\ parse project" destination " " remove item path "myapp" 🪟 windows (command prompt) move myapp\\ move myapp\\ parse local move myapp\\ parse project rmdir myapp step c verify it worked ls la you should see cloud/ and public/ folders in the root (not inside a subfolder) after moving, your repository should look like this your project/ ← your cloned repo ├── git/ ← git directory (from step 1) ├── cloud/ │ └── main js ← your cloud code goes here ├── public/ │ └── index html ← optional web hosting files ├── parse local ← app configuration └── parse project ← project configuration ⚠️ important the cloud/main js file is where your cloud code lives this is what gets deployed to back4app! 2 5 create the github workflows folder now add the folder for github actions ⚠️ important make sure you are inside your cloned repository folder (from step 1) this folder already contains the git directory which is essential for pushing code to github! 🍎 macos / 🐧 linux \# you should already be in your cloned repo folder from step 1 \# if not, navigate to it cd /documents/your repo name \# verify you're in a git repository (should show your branch name) git status \# create the workflows folder mkdir p github/workflows 🪟 windows (powershell) \# you should already be in your cloned repo folder from step 1 \# if not, navigate to it cd \documents\your repo name \# verify you're in a git repository (should show your branch name) git status \# create the workflows folder new item itemtype directory force path " github\workflows" 🪟 windows (command prompt) rem you should already be in your cloned repo folder from step 1 rem if not, navigate to it cd %userprofile%\documents\your repo name rem verify you're in a git repository (should show your branch name) git status rem create the workflows folder mkdir github\workflows 📝 using vs code or cursor open your cloned repository folder in vs code or cursor (the one from step 1) in the explorer sidebar (left panel), right click on empty space select "new folder" name it github (yes, with the dot at the beginning) right click on the github folder select "new folder" name it workflows 2 6 add the workflow file download the the simpledeploy yaml file from here and copy it into the github/workflows/ folder 2 7 verify your project structure after completing this step, your cloned repository should look like this your project/ ← this is your cloned repo folder ├── git/ ← git directory (essential created when you cloned) ├── github/ │ └── workflows/ │ └── simpledeploy yaml ← the deployment workflow ├── cloud/ │ └── main js ← your cloud code ├── public/ ← (optional) web hosting files │ └── index html ├── parse local ← back4app app config ├── parse project ← back4app project config └── (your other files) 📁 workflow file location github/workflows/simpledeploy yaml ⚠️ don't see the git folder? on macos/linux hidden folders (starting with ) may not show by default run ls la in terminal to see them on windows enable "show hidden files" in file explorer settings if git is truly missing you're not in the cloned repository! go back to step 1 and clone your repo properly ✅ success! your cloned repository now has the back4app structure and the workflow file the git folder ensures you can push changes to github step 3 find your back4app app ids you need to find the application id for each of your two back4app apps what is an application id? it's a unique code that identifies your app it looks something like this jroq8xfzsbwlxc1od1abr94ggvtv11axo12kyus0 how to find it log into back4app at back4app com click on your development app from the dashboard in the overview tab (on the left side), look for app id (on the right side) copy the "app id" value write it down or paste it somewhere safe my development app id go back to the dashboard and repeat for your production app my production app id ⚠️ important make sure you don't mix them up! label which is which step 4 edit the workflow file now you'll put your app ids into the workflow file 4 1 open the file open github/workflows/simpledeploy yaml in your code editor 4 2 find lines 38 39 look for this section near the top of the file env \# ┌─────────────────────────────────────────────────────────────────────────┐ \# │ edit these values replace with your actual back4app application ids │ \# └─────────────────────────────────────────────────────────────────────────┘ development app id "your development app id here" production app id "your production app id here" 4 3 replace the placeholder values change the placeholder text to your actual app ids before development app id "your development app id here" production app id "your production app id here" after (example) development app id "jroq8xfzsbwlxc1od1abr94ggvtv11aks8ur08kk" production app id "v9ps0ps4vtbwnvisz0tavq7vydxvc8alo42k096b" ⚠️ important keep the quotation marks around the ids! 4 4 save the file press ctrl + s (windows/linux) or cmd + s (mac) to save step 5 add your secrets to github secrets are like passwords they're kept hidden and secure you need to add two secrets to your github repository what secrets do you need? secret name what it is back4app email the email address you use to log into back4app back4app account key a special key from your back4app account settings 5 1 find your back4app account key if you already created an account key in step 2 2, you can use the same one otherwise log into back4app at back4app com click on your profile icon (top right corner of the dashboard) look for "account keys" in the menu give your account key a name and click the "+" button on the right side copy your new key immediately 💡 tip if you already configured the cli in step 2, you already have an account key you can use the same one for the github secret 5 2 add secrets to github go to your repository on github open your web browser go to github com/your username/your repo name click the "settings" tab it's in the top menu bar of your repository (you need to be the owner or have admin access) find "secrets and variables" in the left sidebar click on it to expand click on "actions" add the first secret (back4app email) click the green "new repository secret" button name type back4app email (exactly like this, all capitals) secret type your back4app email address click "add secret" add the second secret (back4app account key) click "new repository secret" again name type back4app account key (exactly like this, all capitals) secret paste your back4app account key click "add secret" 5 3 verify your secrets after adding both secrets, you should see them listed repository secrets ────────────────── back4app account key updated just now back4app email updated just now ✅ note you won't be able to see the actual values that's normal! github hides them for security step 6 create your branches the workflow uses two branches development and main what are branches? think of branches like parallel versions of your project development where you test new features main the stable version for real users check if you already have these branches 🖥️ using terminal/command line \# navigate to your project cd your project \# see all your branches git branch a look for development and main in the list 🌐 using github website go to your repository on github click the branch dropdown (usually says "main" or "master") see if development and main are listed create missing branches if you need to create the branches create the 'development' branch \# make sure you're in your project folder cd your project \# create and switch to development branch git checkout b development \# push it to github git push u origin development create the 'main' branch \# create and switch to main branch git checkout b main \# push it to github git push u origin main ⚠️ about "master" vs "main" some older repositories use master instead of main this workflow uses main if your repository has master but not main , you have two options option a rename master to main git branch m master main git push u origin main option b edit the workflow file to use master instead of main find this section in simpledeploy yaml on push branches \ development \ main change main to master on push branches \ development \ master step 7 deploy! you're all set up! now let's test it 7 1 commit and push your changes \# add all your changes (including the workflow file) git add \# create a commit git commit m "add deployment workflow" \# push to development branch first (for testing) git checkout development git push origin development 7 2 watch the magic happen go to your repository on github click the "actions" tab you should see a workflow running! the workflow will show each step as it runs ✅ green checkmark = step completed successfully 🔄 yellow spinner = step is running ❌ red x = step failed (click to see what went wrong) 7 3 check the results if everything worked, you'll see ✅ deployment complete! and your back4app development app will have your latest code! how to use it daily once set up, using this workflow is simple for everyday development \# make your changes to the code \# then git add git commit m "describe what you changed" git push origin development → this deploys to your development back4app app when you're ready to release to users \# switch to main branch git checkout main \# merge your tested changes from development git merge development \# push to main git push origin main → this deploys to your production back4app app quick reference action command result test new code git push origin development updates development app release to users git push origin main updates production app troubleshooting ❌ "development app id has not been configured!" what it means you didn't edit the workflow file with your app ids how to fix open github/workflows/simpledeploy yaml find lines 38 39 replace your development app id here with your actual app id save, commit, and push again ❌ "back4app email secret is not set!" what it means github can't find the secret you were supposed to add how to fix go to your repo on github → settings → secrets and variables → actions check if back4app email exists (exact spelling, all capitals) if not, add it (see /#step 5 add your secrets to github ) ❌ "back4app account key secret is not set!" what it means same as above, but for the account key how to fix go to your repo on github → settings → secrets and variables → actions check if back4app account key exists if not, add it (see /#step 5 add your secrets to github ) ❌ workflow doesn't run when i push possible causes wrong branch name the workflow only runs on development and main check your branch git branch workflow file in wrong location it must be at exactly github/workflows/simpledeploy yaml yaml syntax error make sure you didn't accidentally break the file format when editing ❌ "b4a deploy" fails possible causes wrong app id double check that you copied the correct application ids wrong account key your account key might be incorrect or expired no permission make sure your back4app account has access to both apps ❌ health check shows unexpected response what it means the deployment probably worked, but the verification step got an unusual response this is usually okay! the important thing is whether the "deploy to back4app" step succeeded check your back4app dashboard to confirm the deployment worked i need more help! if you're stuck read the error message carefully it usually tells you exactly what's wrong check the actions tab on github click on the failed run, then click on the failed step to see details compare your setup with this guide step by step ask for help include the exact error message when asking glossary new to some of these terms? here's what they mean term what it means branch a separate version of your code like having a "draft" and a "final" copy commit a saved snapshot of your changes, with a message describing what you did push uploading your commits from your computer to github repository (repo) your project's home on github contains all your code and history workflow an automated process that runs when something happens (like pushing code) secret a hidden value (like a password) stored securely in github application id a unique code that identifies your back4app app account key a password like code that proves you own your back4app account cloud code javascript code that runs on back4app's servers cli command line interface a way to control programs by typing commands summary checklist use this checklist to make sure you've completed everything created github/workflows/ folder in your project copied simpledeploy yaml into that folder found your development app id from back4app found your production app id from back4app edited simpledeploy yaml with both app ids (lines 38 39) added back4app email secret to github added back4app account key secret to github created development branch (or confirmed it exists) created main branch (or confirmed it exists) pushed code and saw the workflow run successfully once all boxes are checked, you're done! 🎉 what's next? now that you have automatic deployments working, you might want to set up branch protection prevent accidental pushes to main add collaborators let team members push code too try the advanced workflow check out deploy yaml for more features like automatic code linting (eslint) code formatting (prettier) running tests (jest) more than 2 environments congratulations on setting up your first ci/cd pipeline! 🚀 ci/cd = continuous integration / continuous deployment fancy words for "automatically test and deploy code"