Registry Authentication

If you are using private images, you will need to authenticate with the image registries to pull and push from your account.

Note that on Docker Hub, you can use public images without any authentication being required.

Encrypted Registry Account Credentials

The most common way authenticate with image registries is to provide your account credentials via an encrypted dockercfg file. This keeps your credentials secure while allowing you to push and pull from private registry accounts.

Get your AES encryption key from the General settings page of your Codeship project and save it to your registry as codeship.aes (adding it to the .gitignore file is a good idea so that it does not end up in your repository).

Run the jet encrypt command against your image registry dockercfg file. This typically looks like jet encrypt dockercfg dockercfg.encrypted. but you can name it whatever you’d like.

Note that the DOCKER_REGISTRY endpoint can be changed to reference a registry other than Docker Hub, such as Quay.io, as long as the registry authenticates with the docker login command.

Generating Credentials With A Service

Due to an increasing number of container registry vendors using different methods to generate Docker temporary credentials, we also have support for custom dockercfg credential generation at runtime. By using a custom service within your list of Codeship services, you can integrate with a standard dockercfg generation container for your desired provider.

Credential Inclusion

Note that in these examples we show the registry credential directives used on both Services and Steps at different points. We allow for either configuration in the case of pulling an image from a private registry. In the case of pushing an image to a private registry the registry credential directive must be included on the push step, though.

Docker Hub

Pushing To Docker Hub

After setting up your registry authentication using the encrypted dockercfg file method shown above, you will want to configure your codeship-services.yml:

app:build:image:username/repository_namedockerfile:Dockerfile

The image defined above will be tagged and pushed based on the push step in your codeship-steps.yml file:

Pulling From Docker Hub

After setting up your registry authentication using the encrypted dockercfg file method shown above, you will want to configure your codeship-services.yml or your Dockerfile to reference the image you are pulling:

FROM username/registry_name# ...

You will also need to configure your codeship-steps.yml file to provide your account credentials via the encrypted dockercfg file on every step that uses an image from your Docker Hub account.

Quay.io

Pushing To Quay.io

To use the encrypted dockercfg file authentication method with Quay.io, you will first need to have create robot account with the requires permissions for your Quay repository. Please see the documentation on Robot Accounts for Quay.io on how to set it up for your repository.

Note that permissions can be set per robot account, so if you are seeing authentication failures you should check that the individual robot account being used is configured with appropriate access.

Next, you will need to download the .dockercfg file for this account by heading over to the Robots Account tab in your settings. From there, either credit a new robot account or click on an existing robot account. In the pop-up window, the Docker Configuration tab will have an option to download an auth.json file.

Once you have encrypted this auth.json file using the encrypted dockercfg method, you will want to configure your codeship-services.yml:

Google GCR

Pushing To GCR

To push to Google GCR in your builds, you will want to make use of our service generator method for registry authentication. This is because Google uses a token-based login system.

We maintain an image you can easily add to your push step to generate these credentials for you.

First, you will need to provide your Google credentials as encrypted environment variables for your Google authentication service. Also note that our image name must include your GCR registry path for your push step to authenticate. Here is an example codeship-services.yml:

Now, you will need a push step in your codeship-steps.yml with the dockercfg_service directive. This directive runs the service specified, when it is pushing, to generate the necessary authentication token.

Note that GCR requires the fully registry path in our image name, and the account you are authenticating with Google must have the necessary account permissions as well. Here is an example codeship-steps.yml:

-name:Push To GCRservice:myapptype:pushimage_name:gcr.io/my_org/my_appregistry:https://gcr.iodockercfg_service:dockercfg_generator

This will use the image we maintain for Google authentication to generate credentials on image pull. Note that you will need to have your AWS credentials set via the encrypted environment variables for the generator service, and that the AWS account you are authenticating with will need appropriate IAM permissions.

AWS ECR

Pushing To ECR

To push to AWS ECR in your builds, you will want to make use of our service generator method for registry authentication. This is because AWS uses a token-based login system.

We maintain an image you can easily add to your push step to generate these credentials for you.

First, you will need to provide your AWS credentials as encrypted environment variables for your AWS authentication service. Also note that our image name must include your ECR registry path for your push step to authenticate. Here is an example codeship-services.yml:

Now, you will need a push step in your codeship-steps.yml with the dockercfg_service directive. This directive runs the service specified, when it is pushing, to generate the necessary authentication token.

ECR requires the fully registry path in our image name, and the account you are authenticating with AWS must have the necessary IAM permissions as well. Here is an example codeship-steps.yml:

-name:Push To ECRservice:myapptype:pushimage_name:870119404647.dkr.ecr.us-east-1.amazonaws.com/myappregistry:https://870119404647.dkr.ecr.us-east-1.amazonaws.comdockercfg_service:dockercfg_generator

Note that to authenticate with ECR, you will need to provide the following environment variables via your encrypted environment variables in order to authenticate with AWS successfully:

This will use the image we maintain for AWS authentication to generate credentials on image pull. Note that you will need to have your AWS credentials set via the encrypted environment variables for the generator service, and that the AWS account you are authenticating with will need appropriate IAM permissions.

Now, you will need a push step in your codeship-steps.yml with the dockercfg_service directive. This directive runs the service specified, when it is pushing, to generate the necessary authentication token.

Note that IBM Cloud requires the fully registry path in our image name, and the account you are authenticating with must have at least one namespace configured with the IBM Cloud Container Registry product:

Pulling From IBM Cloud Registry

To pull images from a IBM Cloud Container Registry, you will need to provide the image, including the registry path, as well as use the service generator for authentication in your codeship-services.yml.

This will use the image we maintain for IBM Cloud authentication to generate credentials on image pull. Note that you will need to have the BLUEMIX_API_KEY variable set via encrypted environment variables for the generator service.

Now, you will need a push step in your codeship-steps.yml with the dockercfg_service directive. This directive runs the service specified, when it is pushing, to generate the necessary authentication token.

Note that the Azure Container Service requires the fully registry path in our image name:

This image_tag field can contain a simple string, or be part of a Go template. You can compose your image tag from a variety of provided values. Note that because we use Go for our Regex support, negative regexes and conditional regexes are not supported.

ProjectID (the Codeship defined project ID)

BuildID (the Codeship defined build ID)

RepoName (the name of the repository according to the SCM)

Branch (the name of the current branch)

CommitID (the commit hash or ID)

CommitMessage (the commit message)

CommitDescription (the commit description, see footnote)

CommitterName (the name of the person who committed the change)

CommitterEmail (the email of the person who committed the change)

CommitterUsername (the username of the person who committed the change)

To tag your image based on the Commit ID, use the string "{{ .CommitID }}". You can template together multiple keys into a tag by simply concatenating the strings: "{{ .CiName }}-{{ .Branch }}". Be careful about using raw values, however, since the resulting string will be stripped of any invalid tag characters.

Invalid character / Failed to parse dockercfg

You might see an error like this when pulling a private base image using your encrypted dockercfg file:

Failed to parse dockercfg: invalid character '___' after top-level value

This means that either your dockercfg has a syntax problem or that it was encrypted with an incorrect or incomplete AES key, or an AES key from another project.

Error: “docker: no decryptor available”

This error means that the encrypted file was unable to be decrypted locally. This is because the AES key is missing.

See the instructions above for downloading your AES key locally to address this issue.

Need a key regenerated

If you need a key regenerated, you can submit a ticket to the help desk from your account. Keep in mind that this will leave current encrypted credentials and environmental variables invalid for future builds on Codeship until they are re-encrypted using the new key.

Only Pushing On Certain Branches

If you don’t want to push the image for each build, add a tag entry to the below step and it will only be run on that specific branch or git tag.