Building and deploying an application manually may seem easy when a project is small.
You write code, run tests, create a build, and deploy it.
But as your application grows and changes more frequently, repeating these steps manually becomes inefficient and increases the chance of mistakes.
A CI/CD pipeline solves this by automatically running important development and deployment tasks whenever your code changes.
Your first pipeline does not need to be complicated.
A simple CI/CD pipeline can look like this:
Write Code
↓
Push to GitHub
↓
Install Dependencies
↓
Run Tests
↓
Build Application
↓
Deploy
In this guide, you will build your first CI/CD pipeline step by step using GitHub Actions.
By the end, you will understand how to create a workflow, trigger it automatically, install dependencies, run tests, build your application, use secrets, add deployment, and troubleshoot common pipeline failures.
What Are We Going to Build?
We will create a simple pipeline that automatically runs whenever code is pushed to the repository.
The pipeline will perform:
Git Push
↓
GitHub Actions Starts
↓
Checkout Code
↓
Set Up Environment
↓
Install Dependencies
↓
Run Tests
↓
Build Application
↓
Pipeline Completed
Once this basic pipeline works, we will see how deployment can be added.
This is a good starting point because every step has a clear purpose.
What Do You Need Before Starting?
Before creating the pipeline, you should have:
- A project
- Git installed
- A GitHub account
- A GitHub repository
- At least one test or validation command
- A build command if your project requires building
You should also know basic Git commands such as:
git add .
git commit -m "message"
git push
You do not need advanced DevOps knowledge.
Step 1: Prepare Your Project
We will use a simple Node.js project as the main example because its setup is easy to understand.
The CI/CD concepts are the same for Python, Flutter, React, Flask, and many other technologies.
Suppose your project looks like:
my-app/
│
├── src/
├── tests/
├── package.json
├── package-lock.json
└── README.md
Your package.json may contain scripts such as:
{
"scripts": {
"test": "your-test-command",
"build": "your-build-command"
}
}
The important point is that your project should have commands the pipeline can execute.
For example:
npm test
and:
npm run build
Before automating anything, verify these commands work on your own machine.
Step 2: Create a Git Repository
If Git is not already initialized:
git init
Add your project:
git add .
Create your first commit:
git commit -m "Initial project setup"
Your project is now tracked by Git.
Step 3: Push the Project to GitHub
Create a new repository on GitHub.
Then connect your local project.
For example:
git remote add origin YOUR_REPOSITORY_URL
Set your main branch:
git branch -M main
Push the project:
git push -u origin main
Your source code is now stored in GitHub.
This is important because GitHub Actions workflows run in connection with your repository.
Step 4: Create the GitHub Actions Folder
GitHub Actions looks for workflow files inside:
.github/workflows/
Create:
.github/
└── workflows/
Then create:
ci.yml
Your project becomes:
my-app/
│
├── .github/
│ └── workflows/
│ └── ci.yml
│
├── src/
├── tests/
├── package.json
└── package-lock.json
The ci.yml file will define your pipeline.
Step 5: Give Your Pipeline a Name
Open:
.github/workflows/ci.yml
Add:
name: CI Pipeline
This is the workflow name displayed in GitHub Actions.
You can use names such as:
CI Pipeline
Build and Test
Backend CI
Production Pipeline
For our first pipeline:
name: CI Pipeline
is enough.
Step 6: Choose When the Pipeline Should Run
The pipeline needs a trigger.
For example:
on:
push:
branches:
- main
This means:
Push to main
↓
Start Pipeline
Now every push to the main branch can trigger the workflow.
Run CI on Pull Requests
You usually also want to validate code before it gets merged.
Add:
on:
push:
branches:
- main
pull_request:
branches:
- main
Now the workflow runs when:
Code pushed to main
or:
Pull request targets main
This is a useful basic CI configuration.
Step 7: Create Your First Job
A workflow contains one or more jobs.
Add:
jobs:
build-and-test:
runs-on: ubuntu-latest
build-and-test is the job name.
runs-on specifies the environment where the job will execute.
Here:
ubuntu-latest
means GitHub provides an Ubuntu runner for the job.
Conceptually:
GitHub
↓
Creates Runner
↓
Ubuntu Environment
↓
Runs Your Commands
Step 8: Checkout Your Source Code
The runner starts as a fresh environment.
It needs your repository code.
Add:
steps:
- name: Checkout repository
uses: actions/checkout@v4
The workflow now becomes:
name: CI Pipeline
on:
push:
branches:
- main
pull_request:
branches:
- main
jobs:
build-and-test:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
Now the runner can access your project files.
Step 9: Set Up the Programming Environment
Because our example uses Node.js, the runner needs Node.js.
Add:
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 22
Now the runner has the required Node.js environment.
The flow is:
Runner
↓
Checkout Project
↓
Install Node.js
For another technology, this step would change.
Step 10: Install Dependencies
Our project uses npm dependencies.
Add:
- name: Install dependencies
run: npm ci
Why use:
npm ci
instead of:
npm install
in CI?
When a valid lockfile exists, npm ci performs a clean, reproducible dependency installation based on that lockfile.
This makes it well suited to automated environments.
Step 11: Run Automated Tests
Now add:
- name: Run tests
run: npm test
The pipeline becomes:
Checkout
↓
Set Up Node
↓
Install Dependencies
↓
Run Tests
If the tests fail, the job fails.
That means broken code does not silently continue through the pipeline.
Step 12: Build the Application
If your application has a build step, add:
- name: Build application
run: npm run build
Now your CI workflow performs:
Checkout
↓
Setup
↓
Install
↓
Test
↓
Build
This is already a useful CI pipeline.
Complete First CI Pipeline
Your complete .github/workflows/ci.yml can now look like:
name: CI Pipeline
on:
push:
branches:
- main
pull_request:
branches:
- main
jobs:
build-and-test:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 22
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
- name: Build application
run: npm run build
This is your first working CI pipeline.
Step 13: Commit the Pipeline
Save the file.
Then run:
git add .
Commit:
git commit -m "Add CI pipeline"
Push:
git push
Because your workflow is configured for pushes to main, GitHub Actions should automatically start the workflow when the trigger conditions are met.
Step 14: Check Your Pipeline
Open your GitHub repository.
Go to:
Actions
You should see your workflow.
The run will typically show jobs and steps such as:
CI Pipeline
build-and-test
✓ Checkout repository
✓ Set up Node.js
✓ Install dependencies
✓ Run tests
✓ Build application
If everything passes, the workflow is successful.
You have now built your first CI pipeline.
What Happens When the Pipeline Fails?
Suppose:
npm test
fails.
GitHub Actions will mark that step and job as failed.
Conceptually:
Install Dependencies
↓
Tests
↓
FAILED
↓
Build Does Not Continue
Open the failed step to view its logs.
For example:
Run tests
may show the test that failed.
Fix the problem locally.
Then:
git add .
git commit -m "Fix failing test"
git push
The pipeline runs again.
This feedback loop is one of the main benefits of Continuous Integration.
Add Linting to the Pipeline
If your project has linting configured, add it before tests.
For example:
- name: Run lint
run: npm run lint
The workflow becomes:
Install
↓
Lint
↓
Test
↓
Build
Running fast checks early helps the pipeline fail quickly when basic code-quality issues exist.
Add Dependency Caching
Installing dependencies on every run can take time.
actions/setup-node supports npm dependency caching.
Update the setup step:
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
This can reduce repeated dependency-download work between runs.
The lockfile is still used to determine the dependency state.
Improved CI Pipeline
Your workflow can now look like:
name: CI Pipeline
on:
push:
branches:
- main
pull_request:
branches:
- main
jobs:
build-and-test:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- name: Install dependencies
run: npm ci
- name: Run lint
run: npm run lint
- name: Run tests
run: npm test
- name: Build application
run: npm run build
This is still simple, but it provides useful automated validation.
CI Is Working — Where Does CD Begin?
So far, your pipeline performs Continuous Integration:
Push
↓
Install
↓
Lint
↓
Test
↓
Build
To move toward CI/CD, you add deployment.
Conceptually:
Push
↓
CI
↓
Build Successful
↓
Deploy
However, deployment is different for every platform.
A frontend application, backend API, Docker service, Flutter app, and cloud function all have different deployment commands.
The important first step is understanding where deployment belongs.
Create a Separate Deployment Job
Instead of mixing everything together, deployment can be a separate job.
For example:
jobs:
build-and-test:
runs-on: ubuntu-latest
steps:
# Build and test steps
deploy:
needs: build-and-test
runs-on: ubuntu-latest
steps:
# Deployment steps
The important line is:
needs: build-and-test
It means:
build-and-test
↓
Must Succeed
↓
deploy
Deployment does not start if the required CI job fails.
Deploy Only from the Main Branch
You usually do not want every pull request deploying to production.
You can restrict deployment:
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
Conceptually:
Pull Request
↓
Build + Test
↓
No Production Deployment
but:
Push to main
↓
Build + Test
↓
Deploy
This is a much safer starting workflow.
Basic CI/CD Structure
Your pipeline architecture can now look like:
Pull Request
↓
Build + Test
↓
Ready to Merge
Merge / Push to Main
↓
Build + Test
↓
Deploy
This pattern is simple enough for beginners while still being useful for real projects.
Adding Deployment Secrets
Deployment often requires credentials.
For example:
Cloud API Token
Server Credential
Deployment Token
Hosting Token
Never put real secrets directly inside:
ci.yml
Bad:
env:
API_TOKEN: my-real-secret-token
because that secret becomes part of your repository history.
Instead, use GitHub repository or environment secrets.
Creating a GitHub Actions Secret
Inside your repository, open the appropriate GitHub settings for Actions secrets and variables.
Create a secret such as:
DEPLOY_TOKEN
Then use it in your workflow:
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
The pipeline can use the value without storing the real secret directly in the YAML file.
Example Deployment Job
Because every hosting provider has different commands, a generic deployment job might look like:
deploy:
needs: build-and-test
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Deploy application
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
run: your-deployment-command
Replace:
your-deployment-command
with the command required by your hosting platform.
Do not copy a random deployment command from another provider.
Full Basic CI/CD Pipeline Structure
A practical beginner pipeline now follows:
Developer
↓
Git Push / Pull Request
↓
GitHub Actions
↓
Checkout
↓
Setup Environment
↓
Install Dependencies
↓
Lint
↓
Tests
↓
Build
↓
All Passed?
↓
Main Branch?
↓
Deploy
This is enough to understand the foundation of CI/CD.
Add Environment Variables
Your application may require configuration such as:
API_URL
APP_ENV
DATABASE_HOST
Non-sensitive configuration can be provided using appropriate variables.
Sensitive configuration should use secrets.
For example:
env:
APP_ENV: production
API_TOKEN: ${{ secrets.API_TOKEN }}
Your application can then read these values during the relevant pipeline step.
Never Print Secrets
Avoid commands that expose secrets in pipeline logs.
For example, do not intentionally do:
echo $DEPLOY_TOKEN
Pipeline logs may be visible to people with repository access and may also be retained.
Treat CI/CD logs as potentially sensitive.
Build Artifacts
Sometimes you want to save the output produced by the build.
For example:
Source Code
↓
Build
↓
dist/
The dist directory may contain your production frontend.
For other technologies, an artifact could be:
APK
AAB
JAR
ZIP
Docker image
Compiled binary
GitHub Actions can upload files as workflow artifacts when you need to keep or pass build output.
Upload a Build Artifact
For example:
- name: Upload build artifact
uses: actions/upload-artifact@v4
with:
name: production-build
path: dist/
Now the workflow run can retain that build output according to the configured artifact retention behavior.
This can be useful for:
- Testing
- Deployment
- Debugging
- Release preparation
Build Once, Deploy the Tested Output
A useful CI/CD principle is:
Build
↓
Test
↓
Save Artifact
↓
Deploy Same Artifact
rather than:
Build for Testing
↓
Pass
↓
Build Again Differently
↓
Deploy
Using the same tested artifact reduces the possibility of differences between what was validated and what was deployed.
CI/CD for a Python Project
The overall pipeline does not change much.
Instead of Node.js:
Set Up Python
↓
Install requirements.txt
↓
Run Tests
A basic setup might use:
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install dependencies
run: pip install -r requirements.txt
- name: Run tests
run: pytest
The same CI/CD concept applies.
CI/CD for Flask
A Flask pipeline may look like:
Push
↓
Set Up Python
↓
Install Dependencies
↓
Run Tests
↓
Build / Package if Required
↓
Deploy Flask Application
Example test step:
- name: Run tests
run: pytest
Your deployment step depends on where the Flask application is hosted.
CI/CD for Flutter
A Flutter CI pipeline might look like:
Push
↓
Set Up Flutter
↓
flutter pub get
↓
flutter analyze
↓
flutter test
↓
flutter build
Typical commands include:
flutter pub get
flutter analyze
flutter test
For Android:
flutter build appbundle
or:
flutter build apk
Your actual release pipeline may also need Android signing configuration.
Flutter Android Release Pipeline
A more realistic Android flow is:
Push / Release
↓
Set Up Flutter
↓
Dependencies
↓
Analyze
↓
Tests
↓
Signing Configuration
↓
Build AAB
↓
Release Artifact
↓
Play Store Deployment
Signing credentials must be handled securely through CI secrets or another secure credential-management mechanism.
Do not commit signing secrets directly to the repository.
Flutter iOS CI/CD
iOS builds require a macOS environment.
A simplified pipeline is:
Push
↓
macOS Runner
↓
Set Up Flutter
↓
Install Dependencies
↓
Tests
↓
Configure Signing
↓
Build iOS
↓
Archive
↓
Distribution
iOS CI/CD requires additional setup for certificates, provisioning, and App Store authentication.
For your first CI pipeline, it is often better to automate analysis and testing first, then add signing and store deployment separately.
How to Know Your Pipeline Is Correct
Your pipeline should pass when:
Code is valid
Tests pass
Build succeeds
Required configuration exists
It should fail when:
Tests fail
Build fails
Required dependency cannot install
Required configuration is missing
A pipeline that always passes is not necessarily useful.
Its purpose is to catch real problems.
Test Your Pipeline Intentionally
After creating your first pipeline, intentionally make a test fail.
For example:
Expected: 10
Actual: 11
Push the change.
Verify:
Git Push
↓
Pipeline Starts
↓
Test Fails
↓
Pipeline Fails
Then fix the test or code and push again.
Verify:
Pipeline
↓
Passed
This confirms your CI system is actually protecting the project.
Common Error: Workflow Does Not Start
If your pipeline does not run, check:
Is the YAML file inside .github/workflows/?
Is the file extension .yml or .yaml?
Does the trigger match your branch?
Did you push the workflow file?
Is the YAML valid?
For example, if your trigger is:
branches:
- main
but you push to:
develop
that workflow will not run because of that trigger.
Common Error: Dependency Installation Fails
Suppose:
npm ci
fails.
Check:
package.jsonpackage-lock.json- Node.js version
- Private package authentication
- Dependency compatibility
A command working locally does not always guarantee it will work in CI if the local machine has extra untracked configuration.
Common Error: Tests Pass Locally but Fail in CI
Possible causes include:
Different runtime version
Missing environment variable
Different operating system
Missing service
Timezone difference
Tests depending on local files
Tests depending on execution order
CI exposes assumptions that may be hidden on a developer machine.
That is useful information.
Common Error: Build Passes but Deployment Fails
If:
Build ✓
Test ✓
Deploy ✗
check deployment-specific issues such as:
Expired credentials
Missing secrets
Incorrect permissions
Wrong environment configuration
Hosting service unavailable
Incorrect deployment command
Separate CI failures from deployment failures when troubleshooting.
Common Error: Secret Is Empty
If:
DEPLOY_TOKEN
appears unavailable, check:
- Secret name spelling
- Repository/environment configuration
- Whether that workflow is allowed to access the secret
- Whether the event type receives secrets
- Whether environment approval is required
Never solve the problem by hardcoding the secret into the workflow.
Protect the Main Branch
Once CI is working, consider protecting your important branch.
A useful workflow is:
Feature Branch
↓
Pull Request
↓
CI Checks
↓
Required Checks Pass
↓
Review
↓
Merge to Main
This prevents contributors from accidentally merging code that fails required checks.
Keep Pull Request CI Fast
Developers should receive feedback quickly.
A pull-request pipeline might focus on:
Lint
Unit Tests
Build
while slower checks can run later when appropriate.
The goal is not to remove important testing.
The goal is to organize checks so developers receive useful feedback as early as possible.
Do Not Add Every Tool to Your First Pipeline
Your first pipeline does not need:
10 security scanners
Multiple deployment strategies
Five environments
Complex container orchestration
Large approval chains
Start with:
Install
↓
Lint
↓
Test
↓
Build
Then add deployment.
After that, improve the pipeline based on real project needs.
Recommended First CI/CD Pipeline
For most beginner projects:
Pull Request
↓
Install Dependencies
↓
Lint
↓
Tests
↓
Build
↓
Merge Allowed
After merge:
Main Branch
↓
Install
↓
Test
↓
Build
↓
Deploy
↓
Verify
This is a strong foundation without unnecessary complexity.
CI/CD Security Basics
Even a beginner pipeline should follow a few important security rules.
Never Commit Secrets
Keep credentials outside source code.
Limit Production Access
Only deployment jobs should receive production credentials when possible.
Protect Main Branch
Prevent unreviewed changes from reaching important branches.
Review Workflow Changes
A workflow file can execute commands and potentially access secrets.
Treat changes to:
.github/workflows/
as security-sensitive.
Use Trusted Actions
Third-party workflow actions execute code inside your CI environment.
Use trusted and well-maintained actions, and follow your project’s dependency-security practices.
Your First CI/CD Pipeline Checklist
Before considering your first pipeline complete, verify:
□ Repository is connected to GitHub
□ .github/workflows exists
□ Workflow YAML exists
□ Pipeline has a clear trigger
□ Source code is checked out
□ Runtime is configured
□ Dependencies install successfully
□ Lint/static checks run if available
□ Automated tests run
□ Application builds successfully
□ Failed tests stop the pipeline
□ Secrets are not committed
□ Deployment runs only when intended
□ Production credentials are protected
□ Pipeline logs are understandable
You do not need dozens of stages.
If these fundamentals work correctly, you already have a useful pipeline.
First CI/CD Pipeline Flow
Remember this flow:
Developer
↓
Write Code
↓
Git Commit
↓
Git Push
↓
GitHub Actions
↓
Checkout
↓
Setup Environment
↓
Install Dependencies
↓
Lint
↓
Tests
↓
Build
↓
Deploy
If a required stage fails:
Failure
↓
Stop Pipeline
↓
Check Logs
↓
Fix Problem
↓
Push Again
That feedback cycle is the core of CI/CD.
Frequently Asked Questions
What is the easiest way to create my first CI/CD pipeline?
For a project already hosted on GitHub, GitHub Actions is a convenient place to start because workflow automation is integrated directly with the repository.
You create:
.github/workflows/ci.yml
and define the steps your project needs.
Do I need Docker for CI/CD?
No.
You can create a useful CI/CD pipeline without Docker.
For example:
Push
↓
Install
↓
Test
↓
Build
↓
Deploy
Docker can be introduced later if your architecture requires containers.
Do I need Kubernetes for CI/CD?
No.
Kubernetes is not required for learning or implementing CI/CD.
Do not add it simply because you are building a pipeline.
Do I need automated tests?
A pipeline without meaningful automated validation provides much less protection.
Even a small set of important tests is a useful starting point.
Should every Git push deploy to production?
Usually not.
A common setup is:
Feature Branch
→ Test
and:
Main Branch
→ Test + Deploy
The exact rules depend on your development workflow.
Where should I store deployment passwords and API keys?
Use the CI platform’s secret-management features or an appropriate external secrets system.
Do not store real secrets directly inside your repository.
What happens when a pipeline fails?
The failed job or step is marked as unsuccessful.
Open its logs, identify the problem, fix it, and push another commit.
Can I use CI/CD with Flutter?
Yes.
A Flutter pipeline can automate:
flutter pub get
flutter analyze
flutter test
flutter build
and can later be extended for signed builds and store distribution.
Can I use CI/CD with Flask?
Yes.
A Flask pipeline commonly installs Python dependencies, runs tests, performs required validation, and then deploys the application when all checks succeed.
Is GitHub Actions free?
GitHub provides Actions usage according to the repository/account plan and runner type. Usage limits and billing rules can change, so check the current GitHub Actions documentation for your account rather than relying on fixed numbers in a tutorial.
Final Thoughts
Your first CI/CD pipeline does not need to be complicated.
Start with:
Git Push
↓
Install Dependencies
↓
Run Checks
↓
Run Tests
↓
Build
Once that works reliably, add:
Build
↓
Deploy
Then improve the workflow gradually as your project requires features such as:
Artifacts
Staging
Production approvals
Security checks
Release automation
The most important thing is not how many stages your pipeline contains.
A useful first CI/CD pipeline should automatically answer:
Does this code install, pass the required checks, pass its tests, build correctly, and remain safe to move toward deployment?
Once your pipeline can answer that consistently, you have built a solid foundation for automated software delivery.
