Automate your builds with GitHub Actions

Table of contents

Prerequisites

Complete all the previous sections of this guide, starting with Containerize a Python application. You must have a GitHub account and a verified Docker account to complete this section.

If you didn't create a GitHub repository for your project yet, it is time to do it. After creating the repository, don't forget to add a remote and ensure you can commit and push your code to GitHub.

In your project's GitHub repository, open Settings, and go to Secrets and variables > Actions.
Under the Variables tab, create a new Repository variable named DOCKER_USERNAME and your Docker ID as a value.
Create a new Personal Access Token (PAT) for Docker Hub. You can name this token docker-tutorial. Make sure access permissions include Read and Write.
Add the PAT as a Repository secret in your GitHub repository, with the name DOCKERHUB_TOKEN.

GitHub Actions is a CI/CD automation tool built into GitHub. A workflow is a YAML file that tells GitHub which jobs to run when something happens in your repository, like a push to a branch or a pull request opening. Workflows live in the .github/workflows/ directory of your repository.

In this section, you'll add a workflow that runs your linting, formatting, and type checks on every push to the main branch, then builds your Docker image and pushes it to Docker Hub.

1. Define the GitHub Actions workflow

You can create a GitHub Actions workflow by creating a YAML file in the .github/workflows/ directory of your repository. To do this use your favorite text editor or the GitHub web interface. The following steps show you how to create a workflow file using the GitHub web interface.

If you prefer to use the GitHub web interface, follow these steps:

Go to your repository on GitHub and then select the Actions tab.
Select set up a workflow yourself.
This takes you to a page for creating a new GitHub Actions workflow file in your repository. By default, the file is created under .github/workflows/main.yml. Change the file name to build.yml.

If you prefer to use your text editor, create a new file named build.yml in the .github/workflows/ directory of your repository.

Add the following content to the file:

python-docker-example

# GitHub Actions workflow that runs on every push to main.
# - lint-test: runs pre-commit hooks (Ruff) and Pyright type checks.
# - build_and_push: signs in to Docker Hub and the DHI registry, then
#   builds and pushes the image (with SBOM and provenance attestations).
name: Build and push Docker image

on:
  push:
    branches:
      - main

jobs:
  lint-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
          pip install pre-commit pyright

      - name: Run pre-commit hooks
        run: pre-commit run --all-files

      - name: Run pyright
        run: pyright

  build_and_push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Login to Docker Hardened Images
        uses: docker/login-action@v4
        with:
          registry: dhi.io
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest

Overwrites existing files with the same names. Run from the parent of your project directory.

mkdir -p python-docker-example/.github/workflows && cd python-docker-example
cat > .github/workflows/build.yml <<'__DOCKER_DOCS_SCAFFOLD_EOF__'
# GitHub Actions workflow that runs on every push to main.
# - lint-test: runs pre-commit hooks (Ruff) and Pyright type checks.
# - build_and_push: signs in to Docker Hub and the DHI registry, then
#   builds and pushes the image (with SBOM and provenance attestations).
name: Build and push Docker image

on:
  push:
    branches:
      - main

jobs:
  lint-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
          pip install pre-commit pyright

      - name: Run pre-commit hooks
        run: pre-commit run --all-files

      - name: Run pyright
        run: pyright

  build_and_push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Login to Docker Hardened Images
        uses: docker/login-action@v4
        with:
          registry: dhi.io
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest
__DOCKER_DOCS_SCAFFOLD_EOF__

# Write files as UTF-8 without BOM. Works on Windows PowerShell 5.1 and PowerShell 7+.
function WriteFile([string]$Path, [string]$Content) {
    $full = Join-Path -Path (Get-Location).ProviderPath -ChildPath $Path
    [System.IO.File]::WriteAllText($full, $Content, [System.Text.UTF8Encoding]::new($false))
}

New-Item -ItemType Directory -Force -Path python-docker-example | Out-Null
New-Item -ItemType Directory -Force -Path python-docker-example/.github/workflows | Out-Null
Set-Location python-docker-example
WriteFile '.github/workflows/build.yml' @'
# GitHub Actions workflow that runs on every push to main.
# - lint-test: runs pre-commit hooks (Ruff) and Pyright type checks.
# - build_and_push: signs in to Docker Hub and the DHI registry, then
#   builds and pushes the image (with SBOM and provenance attestations).
name: Build and push Docker image

on:
  push:
    branches:
      - main

jobs:
  lint-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
          pip install pre-commit pyright

      - name: Run pre-commit hooks
        run: pre-commit run --all-files

      - name: Run pyright
        run: pyright

  build_and_push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Login to Docker Hardened Images
        uses: docker/login-action@v4
        with:
          registry: dhi.io
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest
'@

Each GitHub Actions workflow includes one or several jobs. Each job consists of steps. Each step can either run a set of commands or use already existing actions. The action above has three steps:

Login to Docker Hub: Action logs in to Docker Hub using the Docker ID and Personal Access Token (PAT) you created earlier.
Set up Docker Buildx: Action sets up Docker Buildx, a CLI plugin that extends the capabilities of the Docker CLI.
Build and push: Action builds and pushes the Docker image to Docker Hub. The tags parameter specifies the image name and tag. The latest tag is used in this example.

2. Run the workflow

Commit the changes and push them to the main branch. This workflow is runs every time you push changes to the main branch. You can find more information about workflow triggers in the GitHub documentation.

Go to the Actions tab of you GitHub repository. It displays the workflow. Selecting the workflow shows you the breakdown of all the steps.

When the workflow is complete, go to your repositories on Docker Hub. If you see the new repository in that list, it means the GitHub Actions workflow successfully pushed the image to Docker Hub.

Summary

In this section, you learned how to set up a GitHub Actions workflow for your Python application that includes:

Running pre-commit hooks for linting and formatting
Static type checking with Pyright
Building and pushing Docker images

Related information:

Next steps

In the next section, you'll learn how to inspect and generate supply chain attestations for your image. See Secure your supply chain.

Secure your Python image supply chain »

What can I help you with?