Creating a Private Go Module on GitHub and Setting It Up with GitHub Actions

At Zaleos, we love using Go for its simple approach and power in handling many tasks at once. We also use GitHub Actions a lot. It helps us automate our work, making it easier to check and deliver our code right from GitHub. This combo has made our work faster and better, especially when we keep our code private.

Here's how we set up a Go project with GitHub Actions in a private GitHub place, and how to use this in other private projects too.

Step 1: Creating Your Private Go Module on GitHub

1. Create a New Repository: On GitHub, start by creating a new repository for your Go module. Make sure to set the visibility to "Private".
2. Initialize Your Go Module: In your local environment, initialize the new module:

   go mod init github.com/<your-username>/<module-name>
   

3. Push Your Module: Add your Go files, commit, and push them to your newly created GitHub repository.

Step 2: Setting Up GitHub Actions for Your Module

To automate testing and other workflows, we use GitHub Actions:

1. Create a Workflow File: In your module's repository, create a new file under .github/workflows/go.yml.
2. Define Your Workflow:

   name: Go
   
   on:
     push:
       branches: [ main ]
     pull_request:
       branches: [ main ]
   
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
       - uses: actions/checkout@v4
       - name: Set up Go
         uses: actions/setup-go@v4
       - name: Test
         run: go test -v ./...
   

   This workflow checks out the code, sets up Go, and runs build and test commands on push or pull requests to the main branch.

Step 3: Using Your Private Module in Another Project

To use your private module, you must configure authentication for GitHub and set up GOPROXY.

1. Configure Authentication Using .netrc: On your development machine or CI environment, create a .netrc file in the home directory with GitHub credentials:

   machine github.com login <your-username> password <your-personal-access-token>
   

2. Setting Up GOPROXY: In your project or CI environment, set the GOPROXY environment variable to use GitHub's module proxy:

   export GOPROXY=https://github.com/<your-username>
   

Example GitHub Actions Workflow for Using a Private Go Module

In the consuming project's repository, set up a workflow to authenticate and use your private module:

1. Create a Workflow File: Similar to before, create .github/workflows/go.yml.
2. Define Your Workflow Including Authentication:

   name: Go
   
   on:
     push:
       branches: [ main ]
     pull_request:
       branches: [ main ]
   
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
       - uses: actions/checkout@v4
       - name: Setup .netrc
         run: |
           echo -e "machine github.com\nlogin ${{ secrets.GITHUB_USERNAME }}\npassword ${{ secrets.GITHUB_TOKEN }}" > ~/.netrc
       - name: Set up Go
         uses: actions/setup-go@v4
       - name: Build
         run: go build -v ./...
       - name: Test
         run: go test -v ./...
   

   Before running the workflow, ensure you've added GITHUB_USERNAME and GITHUB_TOKEN to your repository's secrets. This workflow configures authentication and runs build and test commands.

By following these steps, you can effectively create, automate, and use private Go modules hosted on GitHub, leveraging GitHub Actions and best practices for module consumption.