Skip to main content

Build/Publish Docker Image

Build a Docker image in a OneDev job and publish it to Docker Hub. This example packages a small static website with Nginx; replace the website build step with your application's build and tests as needed.

Prepare the Repository​

Add an index.html file:

<!doctype html>
<title>OneDev tutorial</title>
<h1>Built by OneDev</h1>

Add a Dockerfile at the repository root:

FROM nginx:alpine
COPY dist/ /usr/share/nginx/html/

The job below creates dist/index.html before building this image.

Configure the Job​

Create or edit .onedev-buildspec.yml, add a job, and configure these steps in order:

  1. Checkout Code: leave the default clone credential selected.

  2. Execute Commands: enable Run In Container, use image alpine:3.22, choose POSIX Compatible Shell with shell sh, and enter:

    mkdir -p dist
    cp index.html dist/
    test -s dist/index.html

  3. Docker Image / Build Image (Buildx): leave Build Path and Dockerfile empty to use the working directory and its Dockerfile. Choose Push to container registry for Output, and set Tags to YOUR_ACCOUNT/YOUR_REPOSITORY:@build_number@. Replace the account and repository with a Docker Hub repository you can push to.

Leave each step's Condition as Successful so a failed build prevents publication.

Enable Image Build in the Executor​

Build Image (Buildx) (BuildImageStep) is disabled by default. It requires a Server Docker Executor or Remote Docker Executor, with Docker and Buildx available on its host.

If no job executors are defined, OneDev uses an auto-discovered executor. Its image build option is disabled too. To enable it, define a job executor explicitly:

  1. Open Administration → Job Executors. Edit the executor that will run the job, or click Add New if none is defined.
  2. For a new executor, select Server Docker Executor to run on the OneDev server, or Remote Docker Executor to run on agents, and give it a name.
  3. Expand Security Settings and turn on Enable Buildx Image Build.
  4. Restrict Applicable Jobs to trusted jobs and save the executor. This option allows the image build step to access files on the executor host.
  5. Select this executor in the job's Job Executor setting. If left unspecified, OneDev selects an applicable executor, so make sure the executor that runs the job has the required option enabled.

Configure Registry Access​

The Docker process used by that executor must be authenticated to Docker Hub. You can use an existing login on the executor host. Alternatively, store a Docker Hub token as a job secret, then add a login under the image step's More Settings / Registry Logins: leave Registry URL empty for Docker Hub, enter the Docker Hub username, and select the secret as Password Secret. Registry logins can also be configured on the executor.

Run and Verify​

Commit the build specification and run the job. Check that checkout, application build, and image publication all succeed. The image tag is the OneDev build number.

From a machine with Docker, verify the published image, replacing the account, repository, and build number:

docker pull YOUR_ACCOUNT/YOUR_REPOSITORY:1
docker run --rm YOUR_ACCOUNT/YOUR_REPOSITORY:1 cat /usr/share/nginx/html/index.html

The output should contain Built by OneDev.