The Red Hat OpenShift GitOps Operator was introduced and released to provide users with a “batteries included” solution for their GitOps workflows. OpenShift users now have a fully supported GitOps solution by using the OpenShift GitOps Operator to install and configure Argo CD for their environment.

Once deployed, Argo CD deploys and manages Application CRD objects, which consist of manifests stored in a Git repository. Many users use private Git repositories on GitHub to store their manifests. In this blog, I will be going over how to connect to private GitHub repositories using a GitHub Token and Argo CD.

Before You Get Started

There are some things you need to have in place before you get started.

• OpenShift 4.8 (or newer) cluster.
• GitHub Account.
• OpenShift GitOps v1.3 (or newer) installed.

Installing OpenShift GitOps (which deploys Argo CD) can be done via the Operator Hub on OpenShift. For more information about how to install OpenShift GitOps, please see the official docs. It’s super easy to install, promise!

Generating Your GitHub Token

Generating your token on GitHub is easy, and can be done in the settings of your account. Simply visit (once you’ve logged in) https://github.com/settings/tokens and click on “Generate new token”. Here you can give your token a name, set an expiration date, and select the scope. You will need this token to have “repo” access. Here is an example:

Once done, scroll down and click “Generate token”. This will take you to a page where you can copy your token. COPY YOUR TOKEN NOW. The token won’t be shown again. If you miss it, you’ll have to regenerate your token.

Once you’ve copied your token, export it to use it later.

$ export GITHUB_TOKEN=<paste your token here>

You can now use this token to access your repo. Next, I will show you how to use this token with Argo CD.

Argo CD Token Access

Starting with OpenShift GitOps v1.3, which uses Argo CD v2, repository access and authentication is done by storing the GitHub token in a Kubernetes Secret in the Namespace where Argo CD is running. This provides a central place where you can define not only the repository but also the credential used to access that repo.

For information about all options available, please refer to the official Argo CD documentation.

The documentation also has information about connecting to a private repository using a GitHub Token. In short, you need to connect to the repository using a non-empty string for the username and the token as the password. Here’s an example using the token that I just exported:

$ cat <<EOF | oc apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: private-bgd-repo
  namespace: openshift-gitops
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  url: https://github.com/christianh814/private-bgd
  password: ${GITHUB_TOKEN}
  username: not-used
EOF

Here, you can see that I set .stringData.username to not-used since it’s not used in authenticating. You can verify it’s been created by running the following command:

$ oc get secret -A -l argocd.argoproj.io/secret-type=repository
NAME           TYPE     DATA    AGE
private-bgd-repo   Opaque   3       5m9s

If you take a look at the Argo CD web UI under the “Repo settings”, you will see that the repo was successfully added - a green check with “Successful” means that Argo CD was able to access the repo.

Argo CD is now ready to deploy the Application that will point to this repo.

Deploying The Application

Deploying the Argo CD Application is the same as any other case. No special parameters need to be set in order to use the private repo. Argo CD will detect which repo you are using and will use the corresponding credentials in the secret. 

Here is an example of an Argo CD Application deploying the manifests that are stored in the private repo that we just added:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: bgd-blue
  namespace: openshift-gitops
spec:
  destination:
    namespace: bgd-blue
    server: https://kubernetes.default.svc
  project: default
  source:
    path: app/overlays/blue/
    repoURL: https://github.com/christianh814/private-bgd
    targetRevision: main
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Here .spec.source.repoURL matches .data.url in the secret. This means that Argo CD will use those credentials to deploy the Application.

$ oc apply -f bgd-private-app.yaml

application.argoproj.io/bgd-blue created

After you create the Application, you should see it in the Web UI.

You can also see the status using the CLI.

$ oc get applications -n openshift-gitops
NAME   SYNC STATUS   HEALTH STATUS
bgd-blue   Synced    Healthy

Using the GitHub token is one of the many ways to connect to a repository.

Other Methods

There are other ways that you can connect to a GitHub repository that doesn’t involve a global access token (a token that can access all your repositories). One method is to use Deployment Keys from GitHub. Deployment Keys are, simply, SSH Keys that only have access to a specific repository.

Once you’ve set up your Deployment Key for the repository, you can upload the private key, using  a Secret, to Argo CD to start using it. In the below example, I am using .data instead of .stringData so I can base64 encode the credentials (this is merely a preference).

$ cat <<EOF | oc apply -f -
apiVersion: v1
kind: Secret
metadata:
  labels:
    argocd.argoproj.io/secret-type: repository
  name: private-ssh-repo
  namespace: openshift-gitops
type: Opaque
data:
  sshPrivateKey: $(base64 -w 0 < ${HOME}/.ssh/id_rsa)
  type: $(echo -n git | base64 -w 0)
  url:  $(echo -n git@github.com:christianh814/private-bgd.git | base64 -w0)
EOF

Note that I am using the SSH syntax as the endpoint URL for my private GitHub repository. The corresponding Argo CD Application will look like this example:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: bgd-green
  namespace: openshift-gitops
spec:
  destination:
    namespace: bgd-green
    server: https://kubernetes.default.svc
  project: default
  source:
    path: app/overlays/green/
    repoURL: git@github.com:christianh814/private-bgd.git
    targetRevision: main
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

As with the Secret containing the credentials, I am using the SSH syntax here as well. I can now deploy this Application.

$ oc apply -f bgd-private-app-ssh.yaml
application.argoproj.io/bgd-green created

This will deploy the second Application using the SSH key to access the repository.

In the above picture, you can see that bgd-blue is using the HTTPS repository, that is using the GitHub token and that bgd-green is using the SSH based repository.

Conclusion

In this blog we went over how to use GitHub tokens to access your git repositories on Argo CD. We also explored how you can connect to the same repository using GitHub deployment keys as well. Finally, we took a look at how to verify that Argo CD can correctly access the repository once you’ve added the proper information.

Curious about what OpenShift GitOps has to offer? Then take a look at our topic page. To learn more about GitOps in general, please make sure to tune in to GitOps Guide to the Galaxy on Red Hat Streaming. We stream live every other Thursday at 3pm Eastern Time. You can catch up on past shows by visiting https://red.ht/gitops.