The basic structure of a CI/CD pipeline with GitHub Actions: automated tests on every change, a Docker image published to GitHub’s registry and a deployment to a protected environment. We use the API from the FastAPI guide as the example, and the complete workflow is in the README.md on the left.
What you’ll learn
- The parts of a GitHub Actions workflow and where the file goes.
- Continuous integration: running the tests on every push and every pull request.
- Building a Docker image and publishing it to GitHub Container Registry.
- Continuous deployment to a protected environment, with its secrets.
- Protecting the main branch so that nothing is merged without passing the tests.
Prerequisites
- A repository on GitHub where you have admin permissions.
- A project with tests and a
Dockerfile. We use the one from the How to build a REST API with FastAPI on Windows guide. - For deployment: a Kubernetes cluster with a
Deploymentcalledtasks-apiand its kubeconfig (see the Kubernetes administration guide). If you don’t have one yet, you can do steps 1 to 4. - Knowing how to commit and push with git.
Step by step
1. Understand the parts of a workflow
A workflow is a YAML file that describes what to do when something happens in the repository. Its main parts:
| Key | What it is for |
|---|---|
name | Name of the workflow in the Actions tab. |
on | What triggers it: push, pull_request, workflow_dispatch (manually), schedule (scheduled)… |
jobs | The jobs. By default they run in parallel, each on a clean machine. |
runs-on | The job’s machine (runner): ubuntu-latest, windows-latest… |
steps | The job’s steps, in order: uses runs a ready-made action; run, commands. |
with · env | Parameters of an action · environment variables. |
needs · if | Dependencies between jobs · conditions for running them. |
secrets | Protected values (passwords, tokens): they are not shown in the logs. |
environment | The target environment, with its own secrets and protection rules. |
permissions | What the automatic GITHUB_TOKEN token can do. |
2. Create the workflow file
Workflows live in the repository’s .github/workflows/ folder. Create ci-cd.yml there:
tasks-api/
├── .github/
│ └── workflows/
│ └── ci-cd.yml
├── main.py
├── test_main.py
├── requirements.txt
└── Dockerfile
Start with the minimum to check that it works. Commit and push, and look at the run in the repository’s Actions tab:
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: echo "Hello from GitHub Actions"
3. Add continuous integration
Replace the test job with one that sets up Python (with dependency caching), installs what is needed and runs the tests. Because it runs on pull_request, every proposed change is validated before it is merged:
jobs:
tests:
runs-on: ubuntu-latest
steps:
- name: Check out the code
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"
cache: pip
- name: Install dependencies
run: pip install -r requirements.txt pytest
- name: Run the tests
run: pytest
4. Build and publish the image
A second job, which only starts if the tests pass (needs) and only on pushes to main (if), builds the image and publishes it to GitHub Container Registry (ghcr.io). It authenticates with the automatic GITHUB_TOKEN, which we give permission to write packages. The image is tagged with the commit (github.sha), so you always know which code is deployed.
image:
needs: tests
if: github.event_name == 'push'
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
- name: Log in to GitHub Container Registry
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and push the image
uses: docker/build-push-action@v6
with:
push: true
tags: ${{ env.IMAGE }}:${{ github.sha }}
5. Store the secrets
In the repository, go to Settings → Secrets and variables → Actions. Secrets for a specific environment are created in Settings → Environments, inside the environment, and only the jobs that use it can see them.
- Create the
productionenvironment. - Inside it, create the
KUBECONFIGsecret with the full contents of the cluster’s kubeconfig file. - Never put a secret in the YAML or print it with
echoin a step: GitHub masks it in the logs, but not in files or artifacts.
6. Deploy to the protected environment
The third job uses the production environment: it picks up its secret, configures kubectl, updates the Deployment’s image and waits for the rollout to finish successfully:
deploy:
needs: image
runs-on: ubuntu-latest
environment: production
steps:
- name: Configure kubectl
run: |
mkdir -p ~/.kube
echo "${{ secrets.KUBECONFIG }}" > ~/.kube/config
- name: Deploy the new image
run: |
kubectl set image deployment/tasks-api api=${{ env.IMAGE }}:${{ github.sha }}
kubectl rollout status deployment/tasks-api --timeout=120s
In Settings → Environments → production you can limit which branches can deploy (only main) and, on paid plans or public repositories, require approval from a person before each deployment.
7. Review the complete workflow
All together, with minimum permissions by default, cancellation of repeated runs and the option to trigger it manually (workflow_dispatch). You also have it in the README.md on the left:
name: CI/CD
on:
push:
branches: [main]
pull_request:
branches: [main]
workflow_dispatch:
# Minimum permissions by default; each job asks for what it needs
permissions:
contents: read
# If a new push arrives on the same branch, the previous run is cancelled
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
env:
IMAGE: ghcr.io/company/tasks-api # always in lowercase
jobs:
tests:
runs-on: ubuntu-latest
steps:
- name: Check out the code
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"
cache: pip
- name: Install dependencies
run: pip install -r requirements.txt pytest
- name: Run the tests
run: pytest
image:
needs: tests
if: github.event_name == 'push'
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
- name: Log in to GitHub Container Registry
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and push the image
uses: docker/build-push-action@v6
with:
push: true
tags: ${{ env.IMAGE }}:${{ github.sha }}
deploy:
needs: image
runs-on: ubuntu-latest
environment: production
steps:
- name: Configure kubectl
run: |
mkdir -p ~/.kube
echo "${{ secrets.KUBECONFIG }}" > ~/.kube/config
- name: Deploy the new image
run: |
kubectl set image deployment/tasks-api api=${{ env.IMAGE }}:${{ github.sha }}
kubectl rollout status deployment/tasks-api --timeout=120s
8. Protect the main branch
In Settings → Rules → Rulesets (or Branches, in older repositories), create a rule for main that requires a pull request and that the tests check has passed. That way nobody merges code that breaks the tests, not even by mistake.
9. Follow each run
In the Actions tab you can see each run with its jobs and the log of each step. If something fails, open the step in red; if it was a one-off, Re-run failed jobs runs only what failed again.
Common errors
The workflow does not run
The file must be in .github/workflows/ and on the branch of the event. For workflow_dispatch (the Run workflow button), the file must already be on the main branch.
Syntax error in the YAML
It is almost always the indentation: YAML uses spaces, never tabs, and each level must be aligned. The Actions tab highlights the line with the error.
“denied: permission_denied” when publishing to ghcr.io
The job’s permissions are missing packages: write, or the package already exists and is not linked to the repository. Check the package’s permissions in Packages → Package settings.
“repository name must be lowercase”
Image names in a container registry are in lowercase. If you use ${{ github.repository }} and the user or organisation has capital letters, write the name by hand in lowercase.
Secrets arrive empty in a pull request
For security, pull requests that come from a fork do not receive secrets. That is why the image and deployment jobs only run on push.
The required reviewers option does not appear
Manual approval for environments (Required reviewers) is only available on public repositories or with paid plans. With the free plan and a private repository, restrict the environment to the main branch or trigger the deployment manually with workflow_dispatch.
kubectl cannot connect to the cluster
The KUBECONFIG secret must contain the complete file, with its line breaks. Also check that the cluster accepts connections from GitHub’s runners (public IPs) or use your own runner inside your network.
Next steps
- Add static and security code analysis (for example, SonarCloud or CodeQL) as another job.
- Enable Dependabot to keep dependencies and action versions up to date.
- Replace the kubeconfig secret with OIDC: GitHub obtains temporary credentials from Azure, AWS or Google Cloud without storing passwords.
- Test against several versions at once with
strategy.matrixand reuse workflows across repositories.