dokku/docs/deployment/methods/git.md

Git Deployment

Subcommands new as of 0.12.0

git:allow-host <host>                              # Adds a host to known_hosts
git:clone [--build] <app> <repository> [<git-ref>] # Creates an app from remote git repo
git:fetch [--build] <app> <repository> [<git-ref>] # Fetch the app at an optional repo object and build the codebase
git:initialize <app>                               # Initialize a git repository for an app
git:public-key                                     # Outputs the dokku public deploy key
git:report [<app>] [<flag>]                        # Displays a git report for one or more apps
git:set <app> <key> (<value>)                      # Set or clear a git property for an app

Git-based deployment has been the traditional method of deploying applications in Dokku. As of v0.12.0, Dokku introduces a few ways to customize the experience of deploying via git push. A Git-based deployment currently supports building applications via:

• Cloud Native Buildpacks
• Herokuish Buildpack
• Dockerfiles

Usage

Initializing an application

When an application is created via git push, Dokku will create the proper pre-receive hook in order to execute the build pipeline. In certain cases - such as when fronting deploys with the git-http-backend - this may not be correctly created. As an alternative, the git:initialize command can be used to trigger this creation:

# on the Dokku host

# overrides any existing pre-receive hook
dokku git:initialize node-js-app

In order for the above command to succeed, the application must already exist.

Warning: If the pre-receive hook was customized in any way, this will overwrite that hook with the current defaults for Dokku.

Changing the deploy branch

By default, Dokku will deploy code pushed to the master branch. In order to quickly deploy a different local branch, the following Git command can be used:

# on the local machine

# where `SOME_BRANCH_NAME` is the name of the branch
git push dokku SOME_BRANCH_NAME:master

In 0.12.0, the correct way to change the deploy branch is to use the git:set Dokku command.

# on the Dokku host

# override for all applications
dokku git:set --global deploy-branch SOME_BRANCH_NAME

# override for a specific app
# where `SOME_BRANCH_NAME` is the name of the branch
dokku git:set node-js-app deploy-branch SOME_BRANCH_NAME

Pushing multiple branches can also be supported by creating a receive-branch plugin trigger in a custom plugin.

Configuring the GIT_REV environment variable

New as of 0.12.0

Application deployments will include a special GIT_REV environment variable containing the current deployment sha being deployed. For rebuilds, this SHA will remain the same.

To configure the name of the GIT_REV environment variable, run the git:set command as follows:

# on the Dokku host

# override for a specific app
dokku git:set node-js-app rev-env-var DOKKU_GIT_REV

This behavior can be disabled entirely on a per-app basis by setting the rev-env-var value to an empty string:

# on the Dokku host

# override for a specific app
dokku git:set node-js-app rev-env-var ""

Keeping the .git directory

By default, Dokku will remove the contents of the .git before triggering a build for a given app. This is generally a safe default as shipping the entire source code history of your app in the deployed image artifact is unnecessary as it increases bloat and potentially can leak information if there are any security issues with your app code.

To enable the .git directory, run the git:set command as follows:

# on the Dokku host

# keep the .git directory during builds
dokku git:set node-js-app keep-git-dir true

The default behavior is to delete this directory and it's contents. To revert to the default behavior, the keep-git-dir value can be set to either an empty string or false.

# on the Dokku host

# delete the .git directory during builds (default)
dokku git:set node-js-app keep-git-dir false

# delete the .git directory during builds (default)
dokku git:set node-js-app keep-git-dir ""

Initializing an app repository from a remote repository

The application must exist before the repository can be initialized

A Dokku app repository can be initialized from a remote git repository via the git:clone command. This command should only be used for an initial sync to a remote repository as it may wipe out any local Dokku history that isn't in sync with the remote. Any repository that can be cloned by the dokku user can be specified.

dokku git:clone node-js-app https://github.com/heroku/node-js-getting-started.git

The git:clone command optionally takes an optional third parameter containing a git reference, which may be a branch, tag, or specific commit.

# specify a branch
dokku git:clone node-js-app https://github.com/heroku/node-js-getting-started.git main

# specify a tag
dokku git:clone node-js-app https://github.com/heroku/node-js-getting-started.git 1

# specify a commit
dokku git:clone node-js-app https://github.com/heroku/node-js-getting-started.git 97e6c72491c7531507bfc5413903e0e00e31e1b0

By default, this command does not trigger an application build. To do so during a git:clone, specify the --build flag.

dokku git:clone --build node-js-app https://github.com/heroku/node-js-getting-started.git

Fetching repository updates from a remote repository

The application must exist before the repository can be initialized

A Dokku app repository can be updated from a remote git repository via the git:fetch command. This command may fail if the specified remote repository cannot be synced from the current Dokku repository state. Any repository that can be cloned by the dokku user can be specified.

dokku git:fetch node-js-app https://github.com/heroku/node-js-getting-started.git

The git:fetch command optionally takes an optional third parameter containing a git reference, which may be a branch, tag, or specific commit.

# specify a branch
dokku git:fetch node-js-app https://github.com/heroku/node-js-getting-started.git main

# specify a tag
dokku git:fetch node-js-app https://github.com/heroku/node-js-getting-started.git 1

# specify a commit
dokku git:fetch node-js-app https://github.com/heroku/node-js-getting-started.git 97e6c72491c7531507bfc5413903e0e00e31e1b0

By default, this command does not trigger an application build. To do so during a git:fetch, specify the --build flag.

dokku git:fetch --build node-js-app https://github.com/heroku/node-js-getting-started.git

Allowing remote repository hosts

By default, the Dokku host may not have access to a server containing the remote repository. This can be initialized via the git:allow-host command.

dokku git:allow-host github.com

Verifying the cloning public key

In order to clone a remote repository, the remote server should have the Dokku host's public key configured. This plugin does not currently create this key, but if there is one available, it can be shown via the git:public-key command.

dokku git:public-key