How to Configure GitHub Actions for a Staging Environment with DockerHub

Deploying reliably is a critical step when building secure internal systems for service-oriented businesses. Automating your staging deployments ensures your team can test thoroughly before touching production.

In this guide, you will learn how to securely link a GitHub Action to a specific GitHub Environment and automate pushing your Docker images directly to DockerHub.

Prerequisites

• Admin access to a GitHub repository.
• A DockerHub account with permissions to push to your target repository.

Step 1: Create a Staging Environment in GitHub

Using GitHub Environments allows you to isolate secrets and set up deployment protection rules, such as requiring manual approvals.

1. Navigate to your GitHub repository.
2. Click on Settings > Environments.
3. Click New environment, name it staging, and save.

Step 2: Generate a Secure DockerHub Access Token

Never use your primary account password for CI/CD pipelines. Instead, use a scoped access token.

1. Log in to your DockerHub dashboard.
2. Navigate to Account Settings > Security > New Access Token.
3. Provide a descriptive name (e.g., "GitHub Actions Staging") and assign Read, Write, Delete permissions.
4. Copy the generated token immediately—you will not be able to view it again.

Step 3: Add DockerHub Secrets to Your GitHub Environment

We will store the credentials in the specific staging environment rather than as repository-wide secrets. This enforces strict least-privilege access.

1. Go back to your repository's Settings > Environments > staging.
2. Scroll down to Environment secrets and click Add secret.
3. Add the following two secrets:
   • DOCKERHUB_USERNAME: Your DockerHub username.
   • DOCKERHUB_TOKEN: The access token generated in Step 2.

Step 4: Create the GitHub Actions Workflow

The environment: staging key in the YAML file is what explicitly connects your job to the secrets you just created.

Create a new file in your repository at .github/workflows/staging-deploy.yml and paste the following configuration:

name: Staging Deployment

on:
  push:
    branches:
      - staging # Triggers automatically when code is pushed to the staging branch

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    environment: staging # Connects the job to your secure GitHub Environment

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

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

      - name: Login to DockerHub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          # Tags the image with both 'staging' and the unique commit SHA for traceability
          tags: your-dockerhub-namespace/your-app:staging-${{ github.sha }}, your-dockerhub-namespace/your-app:staging

Conclusion

Once this YAML file is committed to your repository, pushing any changes to your staging branch will automatically trigger the workflow. GitHub Actions will pull your credentials explicitly from the staging environment securely, build your container, and push the newly built image to DockerHub.