Repo and Project Permissions

Sometimes it may be necessary to limit who can run which commands, such as restricting who can apply changes to production, while allowing more freedom for dev and test environments.

Authorization Workflow

Atlantis performs two authorization checks to verify a user has the necessary permissions to run a command:

1. After a command has been validated, before var files, repo metadata, or pull request statuses are checked and validated.
2. After pre workflow hooks have run, repo configuration processed, and affected projects determined.

Note

The first check should be considered as validating the user for a repository as a whole, while the second check is for validating a user for a specific project in that repo.

Why check permissions twice?

The way Atlantis is currently designed, not all relevant information may be available when the first check happens. In particular, affected projects are not known because pre workflow hooks haven't run yet, so repositories that use hooks to generate or modify repo configurations won't know which projects to check permissions for.

Configuring permissions

Atlantis has two options for allowing instance administrators to configure permissions.

Server option --gh-team-allowlist

The --gh-team-allowlist option allows administrators to configure a global set of permissions that apply to all repositories. For most use cases, this should be sufficient.

External command

For administrators that require more granular and specific permission definitions, an external command can be defined in the server side repo configuration. This command will receive information about the command, repo, project, and GitHub teams the user is a member of, allowing administrators to integrate the permissions validation with other systems or business requirements. An example would be allowing users to apply changes to lower environments like dev and test environments while restricting changes to production or other sensitive environments.

WARNING

These options are mutually exclusive. If an external command is defined, the --gh-team-allowlist option is ignored.

Example

Restrict production changes

This example shows a simple example of how a script could be used to restrict production changes to a specific team, while allowing anyone to work on other environments. For brevity, this example assumes each user is a member of a single team.

server-side-repo-config.yaml

team_authz:
  command: "/scripts/example.sh"

example.sh

#!/bin/bash

# Define name of team allowed to make production changes
PROD_TEAM="example-org/prod-deployers"

# Set variables from command-line arguments for convenience
COMMAND="$1"
REPO="$2"
TEAM="$3"

# Check if we are running the 'apply' command on prod
if [ "${COMMAND}" == "apply" -a "${PROJECT_NAME}" == "prod" ]
then
   # Only the prod team can make this change
   if [ "${TEAM}" == "${PROD_TEAM}" ]
   then
      echo "pass"
      exit 0
   fi
   
   # Print reason for failing and exit
   echo "user \"${USER_NAME}\" must be a member of \"${PROD_TEAM}\" to apply changes to production."
   exit 0
fi 

# Any other command and environment is okay
echo "pass"
exit 0

Reference

External Command Execution

External commands are executed on every authorization check with arguments and environment variables containing context about the command being checked. The command is executed using the following format:

external_command [external_args...] atlantis_command repo [teams...]

Key	Optional	Description
external_command	no	Command defined in server side repo configuration
external_args	yes	Command arguments defined in server side repo configuration
atlantis_command	no	The atlantis command being run (plan, apply, etc)
repo	no	The full name of the repo being executed (format: owner/repo_name)
teams	yes	A list of zero or more teams of the user executing the command

The following environment variables are passed to the command on every execution:

Key	Description
BASE_REPO_NAME	Name of the repository that the pull request will be merged into, ex. atlantis.
BASE_REPO_OWNER	Owner of the repository that the pull request will be merged into, ex. runatlantis.
COMMAND_NAME	The name of the command that is being executed, i.e. plan, apply etc.
USER_NAME	Username of the VCS user running command, ex. acme-user. During an autoplan, the user will be the Atlantis API user, ex. atlantis.

The following environment variables are also passed to the command when checking project authorization:

Key	Description
BASE_BRANCH_NAME	Name of the base branch of the pull request (the branch that the pull request is getting merged into)
COMMENT_ARGS	Any additional flags passed in the comment on the pull request. Flags are separated by commas and every character is escaped, ex. atlantis plan -- arg1 arg2 will result in COMMENT_ARGS=\a\r\g\1,\a\r\g\2.
HEAD_REPO_NAME	Name of the repository that is getting merged into the base repository, ex. atlantis.
HEAD_REPO_OWNER	Owner of the repository that is getting merged into the base repository, ex. acme-corp.
HEAD_BRANCH_NAME	Name of the head branch of the pull request (the branch that is getting merged into the base)
HEAD_COMMIT	The sha256 that points to the head of the branch that is being pull requested into the base. If the pull request is from Bitbucket Cloud the string will only be 12 characters long because Bitbucket Cloud truncates its commit IDs.
PROJECT_NAME	Name of the project the command is being executed on
PULL_NUM	Pull request number or ID, ex. 2.
PULL_URL	Pull request URL, ex. https://github.com/runatlantis/atlantis/pull/2.
PULL_AUTHOR	Username of the pull request author, ex. acme-user.
REPO_ROOT	The absolute path to the root of the cloned repository.
REPO_REL_PATH	Path to the project relative to REPO_ROOT

External Command Result Handling

Atlantis determines if a user is authorized to run the requested command by checking if the external command exited with code 0 and if the last line of output is pass.

# Psuedo-code of Atlantis evaluation of external commands

user_authorized =
  external_command.exit_code == 0
  && external_command.output.last_line == 'pass'

TIP

• A non-zero exit code means the command failed to evaluate the request for some reason (bad configuration, missing dependencies, solar flares, etc).
• If the command was able to run successfully, but determined the user is not authorized, it should still exit with code 0.
  • The command output could contain the reasoning for the authorization failure.