{"id":5173,"date":"2026-11-18T21:20:49","date_gmt":"2026-11-18T21:20:49","guid":{"rendered":"https:\/\/bitflow-solutions.com\/guias-tecnicas\/github-actions-ci-cd\/"},"modified":"2026-11-18T21:20:49","modified_gmt":"2026-11-18T21:20:49","slug":"github-actions-ci-cd","status":"publish","type":"bf_guia","link":"https:\/\/bitflow-solutions.com\/en\/guias-tecnicas\/github-actions-ci-cd\/","title":{"rendered":"Basic CI\/CD structure with GitHub Actions"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">The basic structure of a <strong>CI\/CD<\/strong> pipeline with <strong>GitHub Actions<\/strong>: automated tests on every change, a Docker image published to GitHub\u2019s 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 <strong>README.md<\/strong> on the left.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">What you\u2019ll learn<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>The parts of a GitHub Actions workflow and where the file goes.<\/li>\n\n\n<li>Continuous integration: running the tests on every push and every pull request.<\/li>\n\n\n<li>Building a Docker image and publishing it to GitHub Container Registry.<\/li>\n\n\n<li>Continuous deployment to a protected environment, with its secrets.<\/li>\n\n\n<li>Protecting the main branch so that nothing is merged without passing the tests.<\/li>\n\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Prerequisites<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>A repository on <strong>GitHub<\/strong> where you have admin permissions.<\/li>\n\n\n<li>A project with tests and a <code>Dockerfile<\/code>. We use the one from the <em>How to build a REST API with FastAPI on Windows<\/em> guide.<\/li>\n\n\n<li>For deployment: a Kubernetes cluster with a <code>Deployment<\/code> called <code>tasks-api<\/code> and its kubeconfig (see the Kubernetes administration guide). If you don\u2019t have one yet, you can do steps 1 to 4.<\/li>\n\n\n<li>Knowing how to commit and push with git.<\/li>\n\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\">Step by step<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">1. Understand the parts of a workflow<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">A <strong>workflow<\/strong> is a YAML file that describes what to do when something happens in the repository. Its main parts:<\/p>\n\n\n\n<figure class=\"wp-block-table\"><table><thead><tr><th>Key<\/th><th>What it is for<\/th><\/tr><\/thead><tbody><tr><td><code>name<\/code><\/td><td>Name of the workflow in the Actions tab.<\/td><\/tr><tr><td><code>on<\/code><\/td><td>What triggers it: <code>push<\/code>, <code>pull_request<\/code>, <code>workflow_dispatch<\/code> (manually), <code>schedule<\/code> (scheduled)\u2026<\/td><\/tr><tr><td><code>jobs<\/code><\/td><td>The jobs. By default they run in parallel, each on a clean machine.<\/td><\/tr><tr><td><code>runs-on<\/code><\/td><td>The job\u2019s machine (runner): <code>ubuntu-latest<\/code>, <code>windows-latest<\/code>\u2026<\/td><\/tr><tr><td><code>steps<\/code><\/td><td>The job\u2019s steps, in order: <code>uses<\/code> runs a ready-made action; <code>run<\/code>, commands.<\/td><\/tr><tr><td><code>with<\/code> \u00b7 <code>env<\/code><\/td><td>Parameters of an action \u00b7 environment variables.<\/td><\/tr><tr><td><code>needs<\/code> \u00b7 <code>if<\/code><\/td><td>Dependencies between jobs \u00b7 conditions for running them.<\/td><\/tr><tr><td><code>secrets<\/code><\/td><td>Protected values (passwords, tokens): they are not shown in the logs.<\/td><\/tr><tr><td><code>environment<\/code><\/td><td>The target environment, with its own secrets and protection rules.<\/td><\/tr><tr><td><code>permissions<\/code><\/td><td>What the automatic <code>GITHUB_TOKEN<\/code> token can do.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\">2. Create the workflow file<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Workflows live in the repository\u2019s <code>.github\/workflows\/<\/code> folder. Create <code>ci-cd.yml<\/code> there:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>tasks-api\/\n\u251c\u2500\u2500 .github\/\n\u2502   \u2514\u2500\u2500 workflows\/\n\u2502       \u2514\u2500\u2500 ci-cd.yml\n\u251c\u2500\u2500 main.py\n\u251c\u2500\u2500 test_main.py\n\u251c\u2500\u2500 requirements.txt\n\u2514\u2500\u2500 Dockerfile<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Start with the minimum to check that it works. Commit and push, and look at the run in the repository\u2019s <strong>Actions<\/strong> tab:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>name: CI\n\non:\n  push:\n    branches: [main]\n  pull_request:\n    branches: [main]\n\njobs:\n  tests:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions\/checkout@v4\n      - run: echo \"Hello from GitHub Actions\"<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">3. Add continuous integration<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">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 <code>pull_request<\/code>, every proposed change is validated before it is merged:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>jobs:\n  tests:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Check out the code\n        uses: actions\/checkout@v4\n\n      - name: Set up Python\n        uses: actions\/setup-python@v5\n        with:\n          python-version: \"3.12\"\n          cache: pip\n\n      - name: Install dependencies\n        run: pip install -r requirements.txt pytest\n\n      - name: Run the tests\n        run: pytest<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">4. Build and publish the image<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">A second job, which only starts if the tests pass (<code>needs<\/code>) and only on pushes to <code>main<\/code> (<code>if<\/code>), builds the image and publishes it to <strong>GitHub Container Registry<\/strong> (<code>ghcr.io<\/code>). It authenticates with the automatic <code>GITHUB_TOKEN<\/code>, which we give permission to write packages. The image is tagged with the commit (<code>github.sha<\/code>), so you always know which code is deployed.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>  image:\n    needs: tests\n    if: github.event_name == 'push'\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      packages: write\n    steps:\n      - uses: actions\/checkout@v4\n\n      - name: Log in to GitHub Container Registry\n        uses: docker\/login-action@v3\n        with:\n          registry: ghcr.io\n          username: ${{ github.actor }}\n          password: ${{ secrets.GITHUB_TOKEN }}\n\n      - name: Build and push the image\n        uses: docker\/build-push-action@v6\n        with:\n          push: true\n          tags: ${{ env.IMAGE }}:${{ github.sha }}<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">5. Store the secrets<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">In the repository, go to <strong>Settings \u2192 Secrets and variables \u2192 Actions<\/strong>. Secrets for a specific environment are created in <strong>Settings \u2192 Environments<\/strong>, inside the environment, and only the jobs that use it can see them.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Create the <code>production<\/code> environment.<\/li>\n\n\n<li>Inside it, create the <code>KUBECONFIG<\/code> secret with the full contents of the cluster\u2019s kubeconfig file.<\/li>\n\n\n<li>Never put a secret in the YAML or print it with <code>echo<\/code> in a step: GitHub masks it in the logs, but not in files or artifacts.<\/li>\n\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">6. Deploy to the protected environment<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The third job uses the <code>production<\/code> environment: it picks up its secret, configures <code>kubectl<\/code>, updates the Deployment\u2019s image and waits for the rollout to finish successfully:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>  deploy:\n    needs: image\n    runs-on: ubuntu-latest\n    environment: production\n    steps:\n      - name: Configure kubectl\n        run: |\n          mkdir -p ~\/.kube\n          echo \"${{ secrets.KUBECONFIG }}\" &gt; ~\/.kube\/config\n\n      - name: Deploy the new image\n        run: |\n          kubectl set image deployment\/tasks-api api=${{ env.IMAGE }}:${{ github.sha }}\n          kubectl rollout status deployment\/tasks-api --timeout=120s<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">In <strong>Settings \u2192 Environments \u2192 production<\/strong> you can limit which branches can deploy (only <code>main<\/code>) and, on paid plans or public repositories, require approval from a person before each deployment.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">7. Review the complete workflow<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">All together, with minimum permissions by default, cancellation of repeated runs and the option to trigger it manually (<code>workflow_dispatch<\/code>). You also have it in the README.md on the left:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>name: CI\/CD\n\non:\n  push:\n    branches: [main]\n  pull_request:\n    branches: [main]\n  workflow_dispatch:\n\n# Minimum permissions by default; each job asks for what it needs\npermissions:\n  contents: read\n\n# If a new push arrives on the same branch, the previous run is cancelled\nconcurrency:\n  group: ${{ github.workflow }}-${{ github.ref }}\n  cancel-in-progress: true\n\nenv:\n  IMAGE: ghcr.io\/company\/tasks-api   # always in lowercase\n\njobs:\n  tests:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Check out the code\n        uses: actions\/checkout@v4\n\n      - name: Set up Python\n        uses: actions\/setup-python@v5\n        with:\n          python-version: \"3.12\"\n          cache: pip\n\n      - name: Install dependencies\n        run: pip install -r requirements.txt pytest\n\n      - name: Run the tests\n        run: pytest\n\n  image:\n    needs: tests\n    if: github.event_name == 'push'\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      packages: write\n    steps:\n      - uses: actions\/checkout@v4\n\n      - name: Log in to GitHub Container Registry\n        uses: docker\/login-action@v3\n        with:\n          registry: ghcr.io\n          username: ${{ github.actor }}\n          password: ${{ secrets.GITHUB_TOKEN }}\n\n      - name: Build and push the image\n        uses: docker\/build-push-action@v6\n        with:\n          push: true\n          tags: ${{ env.IMAGE }}:${{ github.sha }}\n\n  deploy:\n    needs: image\n    runs-on: ubuntu-latest\n    environment: production\n    steps:\n      - name: Configure kubectl\n        run: |\n          mkdir -p ~\/.kube\n          echo \"${{ secrets.KUBECONFIG }}\" &gt; ~\/.kube\/config\n\n      - name: Deploy the new image\n        run: |\n          kubectl set image deployment\/tasks-api api=${{ env.IMAGE }}:${{ github.sha }}\n          kubectl rollout status deployment\/tasks-api --timeout=120s<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\">8. Protect the main branch<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">In <strong>Settings \u2192 Rules \u2192 Rulesets<\/strong> (or <em>Branches<\/em>, in older repositories), create a rule for <code>main<\/code> that requires a pull request and that the <strong>tests<\/strong> check has passed. That way nobody merges code that breaks the tests, not even by mistake.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">9. Follow each run<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">In the <strong>Actions<\/strong> 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, <strong>Re-run failed jobs<\/strong> runs only what failed again.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Common errors<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">The workflow does not run<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The file must be in <code>.github\/workflows\/<\/code> and on the branch of the event. For <code>workflow_dispatch<\/code> (the <em>Run workflow<\/em> button), the file must already be on the main branch.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Syntax error in the YAML<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">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.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">\u201cdenied: permission_denied\u201d when publishing to ghcr.io<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The job\u2019s <code>permissions<\/code> are missing <code>packages: write<\/code>, or the package already exists and is not linked to the repository. Check the package\u2019s permissions in <em>Packages \u2192 Package settings<\/em>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">\u201crepository name must be lowercase\u201d<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Image names in a container registry are in lowercase. If you use <code>${{ github.repository }}<\/code> and the user or organisation has capital letters, write the name by hand in lowercase.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Secrets arrive empty in a pull request<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">For security, pull requests that come from a fork do not receive secrets. That is why the image and deployment jobs only run on <code>push<\/code>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">The required reviewers option does not appear<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Manual approval for environments (<em>Required reviewers<\/em>) is only available on public repositories or with paid plans. With the free plan and a private repository, restrict the environment to the <code>main<\/code> branch or trigger the deployment manually with <code>workflow_dispatch<\/code>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">kubectl cannot connect to the cluster<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The <code>KUBECONFIG<\/code> secret must contain the complete file, with its line breaks. Also check that the cluster accepts connections from GitHub\u2019s runners (public IPs) or use your own runner inside your network.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Next steps<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Add static and security code analysis (for example, SonarCloud or CodeQL) as another job.<\/li>\n\n\n<li>Enable Dependabot to keep dependencies and action versions up to date.<\/li>\n\n\n<li>Replace the kubeconfig secret with OIDC: GitHub obtains temporary credentials from Azure, AWS or Google Cloud without storing passwords.<\/li>\n\n\n<li>Test against several versions at once with <code>strategy.matrix<\/code> and reuse workflows across repositories.<\/li>\n\n<\/ul>\n\n\n","protected":false},"excerpt":{"rendered":"<p>A complete pipeline with GitHub Actions: tests on every push and pull request, a Docker image in GitHub Container Registry and deployment to a protected environment, with a workflow ready to copy.<\/p>\n","protected":false},"featured_media":0,"template":"","bf_tecnologia":[104],"bf_nivel":[108],"class_list":["post-5173","bf_guia","type-bf_guia","status-publish","hentry","bf_tecnologia-devops-en","bf_nivel-basic"],"acf":[],"_links":{"self":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_guia\/5173","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_guia"}],"about":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/types\/bf_guia"}],"version-history":[{"count":0,"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_guia\/5173\/revisions"}],"wp:attachment":[{"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/media?parent=5173"}],"wp:term":[{"taxonomy":"bf_tecnologia","embeddable":true,"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_tecnologia?post=5173"},{"taxonomy":"bf_nivel","embeddable":true,"href":"https:\/\/bitflow-solutions.com\/en\/wp-json\/wp\/v2\/bf_nivel?post=5173"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}