Setting up GitHub Package Registry with Docker and Golang
Tags: docker, devops, go, github
Published: 2019-10-05 16:12:06

_Note: This was originally posted at [martinheinz.dev](https://martinheinz.dev/blog/6)_


Generally, for any programming language, to run your application you need to create some kind of package (`npm` for _JavaScript_, `NuGet` for _C#_, ...) and then store it somewhere. In case of _Docker_, people usually just throw their images into _Docker Hub_, but we now have new alternative here...

The alternative is _GitHub Package Registry_ - it has been in beta for a while now and it seems that more and more people are getting access to it, so it feels like the time has come to explore its features, here specifically for _Docker_ and _Go_ projects.

This post is part of the series _"All You Need For Your Next Golang Project"_, if that sound interesting, go ahead and checkout previous part [here](https://dev.to/martinheinz/ultimate-setup-for-your-next-golang-project-5dae).

_Note: This article is applicable to any project using docker images, not just Golang._

## Why Use GitHub Registry

First of all, why should you even consider switching from, let's say, _Docker Hub_ or any other registry, to _GitHub Package Registry_:

- If you are already using _GitHub_ as your SCM, then it makes sense to use _GitHub Package Registry_, as it allows you to keep everything in one place instead of pushing your packages elsewhere.
- There is another shiny new (_beta_) feature of _GitHub_ - _Actions_, which you can leverage in conjunction with _GitHub Package Registry_ (more on this in another post...).
- Even though I consider _Docker_ images superior to e.g. `npm` packages, you can also push those to the _GitHub Package Registry_, if you prefer _non-Docker_ artifacts.

## Let's Do It!

So, now, let's see how to use it. Let's start with building and tagging your image:

_Note: If you are working with Go, then you might want to checkout [my repository here](https://github.com/MartinHeinz/go-project-blueprint), where all the GitHub Package Registry fun is already tied into Makefile targets._

```shell
docker build -t  docker.pkg.github.com/<gh-username>/<gh-repo-name>/<image-name>:<version> .

# For Example
docker build -t  docker.pkg.github.com/martinheinz/go-project-blueprint/blueprint:latest .
```

To be able to push images to _GitHub Package Registry_, you need to name it using format shown above - which really is just URL of registry with your _GitHub_ username and repository name.

Next, how do we access it?

First, to be able to authenticate ourselves with _GitHub Package Registry_, we need to create personal access token. This access token must have `read:packages` and `write:packages` scope and additionally in case you have a private repository, you will have to include `repo` scope as well.

There is already very nice guide on _GitHub_ help website on how to create personal token, so I'm not gonna copy and paste the steps here. You can read about it [here](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line)

Now, that we have personal token let's login:

```bash
docker login docker.pkg.github.com -u <USERNAME> -p <GITHUB_TOKEN>

# For Example:
docker login docker.pkg.github.com -u MartinHeinz -p dgni723a3k67fsdj65e # Not an actual token, so don't even try
```

Finally, time to push our image:

```shell
docker push docker.pkg.github.com/<gh-username>/<gh-repo-name>/<image-name>:<version>

# For Example:
docker push docker.pkg.github.com/martinheinz/go-project-blueprint/blueprint:latest
```

And obviously you can also pull the image:

```shell
docker pull docker.pkg.github.com/<gh-username>/<gh-repo-name>/<image-name>:<version>

# For Example:
docker pull docker.pkg.github.com/martinheinz/go-project-blueprint/blueprint:latest
```

## Use It in Your CI/CD Pipeline

Last thing we might want to to do with _GitHub Package Registry_ is to integrate it with CI/CD tools. Let's look at how it can be done with _Travis_ (_Full `.travis.yml` can be found in my repository [here](https://github.com/MartinHeinz/go-project-blueprint/blob/master/.travis.yml)_):

```yaml
# ...
- language: go  # Push if on master
      services:
        - docker
      if: branch = master
      script:
        - export GO111MODULE=on
        - go mod vendor  # Download dependencies
        # Important stuff start here &#x1F447;
        - echo "$DOCKER_PASSWORD" | docker login docker.pkg.github.com -u "$DOCKER_USERNAME" --password-stdin
        - docker build -t  docker.pkg.github.com/martinheinz/go-project-blueprint/blueprint:latest .
        - docker push docker.pkg.github.com/martinheinz/go-project-blueprint/blueprint:latest
# ...
```

As you can see above, you can run `build` and `push` the same way as on your machine, the only difference is the `docker login`. Here, we use environment variables specified in _Travis_ UI. Username gets passed to the login command through `-u` parameter and password using `echo` into `stdin`, this is needed, so that we don't end-up with our personal _GitHub_ token being printed in _Travis_ logs.

So, how do we set those environment variables? These are the steps:

- Navigate to your _Travis_ job settings for your repository e.g. <https://travis-ci.com/MartinHeinz/go-project-blueprint/settings>
- Scroll down to _Environment Variables_ section
- Set variable name to `DOCKER_USERNAME` and `DOCKER_PASSWORD` respectively. In case of password (_GitHub_ token) make sure, that _Display value in build log_ is set to false.
- Click _Add_ and trigger the build

If you are not using _Travis_ and want to use _GitHub Webhook_ to trigger build, then you can use [`RegistryPackageEvent`](https://developer.github.com/v3/activity/events/types/#registrypackageevent). This could be useful if you are using for example _Jenkins_, _OpenShift_ or _Kubernetes_ and want to trigger deployment every time your package is published or updated in _GitHub Package Registry_.

## Words of Caution

One thing you should keep in mind when using _GitHub Package Registry_ is that you can't delete packages that you push to registry. This is so that you don't break projects that depend on your package. You can request package deletion from _GitHub Support_, but you should not count on them actually deleting anything.

## Conclusion

I hope after reading this, you will give the _GitHub Package Registry_ a shot. If you don't have _beta_ access yet, you can sign up [here](https://github.com/features/package-registry/signup). In case you have any questions, don't hesitate to reach out to me or you can also have a look at my [repository](https://github.com/MartinHeinz/go-project-blueprint), where you can find examples of _GitHub Package Registry_ usage.

### Resources
- <https://github.com/features/package-registry>
- <https://help.github.com/en/articles/about-github-package-registry>