All guides
  1. Home
  2. Technical guides
  3. DevOps

DevOpsBasic level

Basic CI/CD structure with GitHub Actions

6 min read

All guides

Basic CI/CD structure with GitHub Actions

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 Deployment called tasks-api and 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:

KeyWhat it is for
nameName of the workflow in the Actions tab.
onWhat triggers it: push, pull_request, workflow_dispatch (manually), schedule (scheduled)…
jobsThe jobs. By default they run in parallel, each on a clean machine.
runs-onThe job’s machine (runner): ubuntu-latest, windows-latest…
stepsThe job’s steps, in order: uses runs a ready-made action; run, commands.
with · envParameters of an action · environment variables.
needs · ifDependencies between jobs · conditions for running them.
secretsProtected values (passwords, tokens): they are not shown in the logs.
environmentThe target environment, with its own secrets and protection rules.
permissionsWhat 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 production environment.
  • Inside it, create the KUBECONFIG secret with the full contents of the cluster’s kubeconfig file.
  • Never put a secret in the YAML or print it with echo in 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.matrix and reuse workflows across repositories.

Share

More guides on

See all guides

Other technical guides

See all guides

APIsIntermediate

Basic structure of an API in IBM API Connect 10

How an API is structured in IBM API Connect 10: OpenAPI contract with x-ibm-configuration, Client ID and Client Secret, product with plans and limits, and validation and publishing with the apic CLI.

Read the guide 7 min read

IntegrationIntermediate

TIBCO ActiveSpaces 5.2: basic administration commands

The day-to-day commands in TIBCO ActiveSpaces 5.2: realm service on FTL servers, tibdg, grid definition, tables, starting processes, status, scaling with copysets, checkpoints and logs.

Read the guide 8 min read

DevelopmentBasic

Java Spring Boot development best practices

The practices that make the biggest difference in a Spring Boot service: structure, constructor injection, DTOs, validation, errors, configuration, transactions, logs, comments, tests and automated quality.

Read the guide 7 min read

Contact

Build your next competitive advantage today

Let’s talk about how we can help you. We will reply with a clear technical proposal, with no obligation.

Request information

Fields marked with are required.