- When reporting issues, please include the output of
atlantis version
. - Also include the steps required to reproduce the problem if possible and applicable. This information will help us review and fix your issue faster.
- When sending lengthy log-files, consider posting them as a gist (https://gist.github.com). Don't forget to remove sensitive data from your logfiles before posting (you can replace those parts with "REDACTED").
We take security issues seriously. Please email us directly at security [at] runatlantis.io instead of opening an issue.
- To view the generated website locally, run
yarn website:dev
and then open your browser to http://localhost:8080. - The website will be regenerated when your pull request is merged to master.
- Clone the repo from https://github.com/runatlantis/atlantis/
- Compile Atlantis:
go install
- Run Atlantis:
If you get an error like
atlantis server --gh-user <your username> --gh-token <your token> --repo-allowlist <your repo> --gh-webhook-secret <your webhook secret> --log-level debug
command not found: atlantis
, ensure that$GOPATH/bin
is in your$PATH
.
Docker compose is set up to start an atlantis container and ngrok container in the same network in order to expose the atlantis instance to the internet. In order to do this, create a file in the repository called atlantis.env
and add the required env vars for the atlantis server configuration.
e.g.
ATLANTIS_GH_APP_ID=123
ATLANTIS_GH_APP_KEY_FILE="/.ssh/somekey.pem"
ATLANTIS_GH_WEBHOOK_SECRET=12345
Note: ~/.ssh
is mounted to allow for referencing any local ssh keys
Following this just run:
make build-service
docker-compose up
If the ngrok container is restarted, the url will change which is a hassle. Fortunately, when we make a code change, we can rebuild and restart the atlantis container easily without disrupting ngrok.
e.g.
make build-service
docker-compose up --detach --build
make test
. If you want to run the integration tests that actually run real terraform
commands, run make test-all
.
docker run --rm -v $(pwd):/go/src/github.com/runatlantis/atlantis -w /go/src/github.com/runatlantis/atlantis runatlantis/testing-env make test
Or to run the integration tests
docker run --rm -v $(pwd):/go/src/github.com/runatlantis/atlantis -w /go/src/github.com/runatlantis/atlantis runatlantis/testing-env make test-all
- Create a test terraform repository in your GitHub.
- Create a personal access token for Atlantis. See Create a GitHub token.
- Start Atlantis in server mode using that token:
atlantis server --gh-user <your username> --gh-token <your token> --repo-allowlist <your repo> --gh-webhook-secret <your webhook secret> --log-level debug
- Download ngrok from https://ngrok.com/download. This will enable you to expose Atlantis running on your laptop to the internet so GitHub can call it.
- When you've downloaded and extracted ngrok, run it on port
4141
:
ngrok http 4141
- Create a Webhook in your repo and use the
https
url thatngrok
printed out after runningngrok http 4141
. Be sure to append/events
so your webhook url looks something likehttps://efce3bcd.ngrok.io/events
. See Add GitHub Webhook. - Create a pull request and type
atlantis help
. You should see the request in thengrok
and Atlantis logs and you should also see Atlantis comment back.
ctx.Log
should be available in most methods. If not, pass it down.- levels:
- debug is for developers of atlantis
- info is for users (expected that people run on info level)
- warn is for something that might be a problem but we're not sure
- error is for something that's definitely a problem
- ALWAYS logs should be all lowercase (when printed, the first letter of each line will be automatically capitalized)
- ALWAYS quote any string variables using %q in the fmt string, ex.
ctx.Log.Info("cleaning clone dir %q", dir)
=>Cleaning clone directory "/tmp/atlantis/lkysow/atlantis-terraform-test/3"
- NEVER use colons "
:
" in a log since that's used to separate error descriptions and causes- if you need to have a break in your log, either use
-
or,
ex.failed to clean directory, continuing regardless
- if you need to have a break in your log, either use
- ALWAYS use lowercase unless the word requires it
- ALWAYS use
errors.Wrap(err, "additional context...")"
instead offmt.Errorf("additional context: %s", err)
because it is less likely to result in mistakes and gives us the ability to trace call stacks - NEVER use the words "error occurred when...", or "failed to..." or "unable to...", etc. Instead, describe what was occurring at time of the error, ex. "cloning repository", "creating AWS session". This will prevent errors from looking like
Error setting up workspace: failed to run git clone: could find git
and will instead look like
Error: setting up workspace: running git clone: no executable "git"
This is easier to read and more consistent
- place tests under
{package under test}_test
to enforce testing the external interfaces - if you need to test internally i.e. access non-exported stuff, call the file
{file under test}_internal_test.go
- use our testing utility for easier-to-read assertions:
import . "github.com/runatlantis/atlantis/testing"
and then useAssert()
,Equals()
andOk()
We use pegomock for mocking. If you're modifying any interfaces that are mocked, you'll need to regen the mocks for that interface.
If you see errors like:
# github.com/runatlantis/atlantis/server/events [github.com/runatlantis/atlantis/server/events.test]
server/events/project_command_builder_internal_test.go:567:5: cannot use workingDir (type *MockWorkingDir) as type WorkingDir in field value:
*MockWorkingDir does not implement WorkingDir (missing ListAllFiles method)
Then you've likely modified an interface and now need to update the mocks.
Each interface that is mocked has a go:generate
command above it, e.g.
//go:generate pegomock generate -m --use-experimental-model-gen --package mocks -o mocks/mock_project_command_builder.go ProjectCommandBuilder
type ProjectCommandBuilder interface {
BuildAutoplanCommands(ctx *CommandContext) ([]models.ProjectCommandContext, error)
}
To regen the mock, run go generate
on that file, e.g.
go generate server/events/project_command_builder.go
If you get an error about pegomock
not being available, install it:
go get github.com/petergtz/pegomock/...
- Update version number in
main.go
. - Update image tag version in the kustomize/bundle.yaml.
- Update
CHANGELOG.md
with latest release number and information (this URL might be useful: https://github.com/runatlantis/atlantis/compare/v0.3.5...master) - Create a pull request and merge to master
- Check out master and fetch latest
- Run
make release
- Go to https://github.com/runatlantis/atlantis/releases and click "Draft a new release"
- Prefix version with
v
- The title of the release is the same as the tag (ex. v0.2.2)
- Fill in description by copying from the CHANGELOG just without the Downloads section
- Drag in binaries made with
make release
- Prefix version with
- Re-run master branch build to ensure tag gets pushed to Docker hub: https://hub.docker.com/r/runatlantis/atlantis/tags/
- Update the default version in
Chart.yaml
in the official Helm chart.