Subcommands introduced in 0.12.0
git:allow-host <host> # Adds a host to known_hosts
git:auth <host> [<username> <password>] # Configures netrc authentication for a given git server
git:from-archive [--archive-type ARCHIVE_TYPE] <app> <archive-url> [<git-username> <git-email>] # Updates an app's git repository with a given archive file
git:from-image [--build-dir DIRECTORY] <app> <docker-image> [<git-username> <git-email>] # Updates an app's git repository with a given docker image
git:generate-deploy-key # Generates a deploy ssh key
git:load-image [--build-dir DIRECTORY] <app> <docker-image> [<git-username> <git-email>] # Updates an app's git repository with a docker image loaded from stdin
git:sync [--build] <app> <repository> [<git-ref>] # Clone or fetch an app from remote git repo
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:status <app> # Show the working tree status for an app
git:unlock <app> [--force] # Removes previous git clone folder for new deployment
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:
Pushing from a shallow clone is not currently supported and may have undefined behavior. Please unshallow your local repository before pushing to a Dokku app to avoid potential errors in the deployment process.
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:
In order for the above command to succeed, the application must already exist.
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:
0.12.0, the correct way to change the deploy branch is to use the
git:set Dokku command.
As of 0.22.1, Dokku will also respect the first pushed branch as the primary branch, and automatically set the
deploy-branch value at that time.
Pushing multiple branches can also be supported by creating a receive-branch plugin trigger in a custom plugin.
GIT_REV environment variable¶
Introduced in 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:
This behavior can be disabled entirely on a per-app basis by setting the
rev-env-var value to an empty string:
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:
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
Please keep in mind that setting
true may result in unstaged changes shown within the built container due to the build process generating application changes within the built app directory.
Initializing an app repository from a remote repository¶
Introduced in 0.23.0
A Dokku app repository can be initialized or updated from a remote git repository via the
git:sync command. This command will either clone or fetch updates from a remote repository and has undefined behavior if the history cannot be fast-fowarded to the referenced repository reference. Any repository that can be cloned by the
dokku user can be specified.
The application must exist before the repository can be initialized
git:sync 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:sync node-js-app https://github.com/heroku/node-js-getting-started.git main
# specify a tag
dokku git:sync node-js-app https://github.com/heroku/node-js-getting-started.git 1
# specify a commit
dokku git:sync 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:sync, specify the
Initializing from private repositories¶
Introduced in 0.24.0
Initializing from a private repository requires one of the following:
- A Public SSH Key (
id_rsa.pubfile) configured on the remote server, with the associated private key (
id_rsa) in the Dokku server's
- A configured
Dokku provides the
git:auth command which can be used to configure a
netrc entry for the remote server. This command can be used to add or remove configuration for any remote server.
For syncing to a private repository stored on a remote Git product such as GitHub or GitLab, Dokku's recommendation is to use a personal access token on a bot user where possible. Please see your service's documentation for information regarding the recommended best practices.
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
Note that this command is currently not idempotent and may add duplicate entries to the
Creating a cloning ssh key pair¶
Introduced in 0.33.0
While most repositories can be authenticated to via the
git:auth command, some users may prefer to use an ssh key. This can be generated via the
git:generate-deploy-key command, which generates a passwordless ed25519 key-pair.
Generating public/private ed25519 key pair.
Your identification has been saved in /home/dokku/.ssh/id_ed25519
Your public key has been saved in /home/dokku/.ssh/id_ed25519.pub
The key fingerprint is:
The key's randomart image is:
| ..o |
| + |
| . . |
| . o =|
| So . + ++|
| .=.o.. +..|
| ++oo..*o. |
| oo o%*oo=|
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 can be shown via the
If there is no key, an error message is shown that displays the command that can be run on the Dokku server to generate a new public/private ssh key pair.