Repository-level Environment Variables and Secrets in GitHub Actions

When working with GitHub Actions, environment variables and secrets are powerful tools that help you configure workflows in a flexible and secure way. While workflow, job, and step-level variables are useful, sometimes you need variables that are available across all workflows in a repository. This is where repository-level environment variables and secrets come in.

In this article, we’ll break down how repository-level variables and secrets work, why they are useful, and how you can manage them effectively. We’ll also see how to use them in a real-world example: building and pushing a Docker image.

---

What are Repository-level Variables?

Repository-level environment variables are key-value pairs defined in your repository’s settings. They are accessible to all workflows in that repository, without needing to redefine them in every workflow file.

For example:

• Common Docker tags

• Application environment names (like STAGING, PROD)

• URLs or constants that rarely change

They’re stored in plain text, so they are suitable for non-sensitive data.

---

What are Repository-level Secrets?

Secrets are similar to variables, but they are encrypted and hidden. They are designed for storing sensitive data such as:

• API keys

• Database passwords

• Cloud provider credentials

• DockerHub tokens

Secrets are masked in logs and cannot be retrieved once set, making them the secure way to pass sensitive information into workflows.

---

How to Set Them

1. Go to your GitHub repository.

2. Navigate to:
   Settings → Secrets and variables → Actions

3. You’ll find two tabs:

   • Variables → for non-sensitive values

   • Secrets → for sensitive values

4. Add your desired key-value pairs.

For example:

• Variable: DOCKER_IMAGE_NAME = myapp

• Secret: DOCKERHUB_TOKEN = <your token>

---

Using Them in Workflows

Once defined, you can access these directly in your YAML workflow:

name: Docker Build and Push

on: [push]

jobs:
  docker:
    runs-on: ubuntu-latest

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

      - name: Log in to DockerHub
        run: echo "${{ secrets.DOCKERHUB_TOKEN }}" | docker login -u ${{ secrets.DOCKERHUB_USER }} --password-stdin

      - name: Build Docker image
        run: docker build -t ${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }} .

      - name: Push Docker image
        run: docker push ${{ vars.DOCKER_IMAGE_NAME }}:${{ github.sha }}

---

Key Points to Remember

• Use repository-level variables for constants that don’t need to be hidden.

• Use secrets for anything sensitive.

• Variables are available using ${{ vars.NAME }}.

• Secrets are available using ${{ secrets.NAME }}.

• Both variables and secrets are available in all workflows in the repository.

---

Real-world Example: Docker Deployment

Imagine you’re deploying a service using DockerHub. Instead of hardcoding image names and credentials in multiple workflow files:

• Store DOCKER_IMAGE_NAME as a variable.

• Store DOCKERHUB_USER and DOCKERHUB_TOKEN as secrets.

• Reference them directly in your workflows.

This keeps your workflows clean, reusable, and secure.

---

Conclusion

Repository-level variables and secrets are essential for building maintainable and secure GitHub Actions workflows. They allow you to centralize configuration, avoid duplication, and keep sensitive data safe. Whether you’re building Docker images, deploying to cloud services, or running CI pipelines, understanding how to use repository-level variables and secrets will save you time and headaches.