github.com/danp/terraform@v0.9.5-0.20170426144147-39d740081351/website/source/docs/enterprise/runs/starting.html.md (about)

     1  ---
     2  layout: "enterprise"
     3  page_title: "Starting - Runs - Terraform Enterprise"
     4  sidebar_current: "docs-enterprise-runs-starting"
     5  description: |-
     6    How to start runs in Terraform Enterprise.
     7  ---
     8  
     9  
    10  # Starting Terraform Runs
    11  
    12  There are a variety of ways to queue a Terraform run in Terraform Enterprise. In addition to
    13  `terraform push`, you can connect your environment
    14  to GitHub and runs based on new commits. You can
    15  also intelligently queue new runs when linked artifacts are uploaded or changed.
    16  Remember from the [previous section about Terraform runs](/docs/enterprise/runs)
    17  that it is safe to trigger many plans without consequence since Terraform plans
    18  do not change infrastructure.
    19  
    20  
    21  ## Terraform Push
    22  
    23  Terraform `push` is a [Terraform command](https://terraform.io/docs/commands/push.html)
    24  that packages and uploads a set of Terraform configuration and directory to the platform. This then creates a run
    25  which performs `terraform plan` and `terraform apply` against the uploaded
    26  configuration.
    27  
    28  The directory is included in order to run any associated provisioners,
    29  that might use local files. For example, a remote-exec provisioner
    30  that executes a shell script.
    31  
    32  By default, everything in your directory is uploaded as part of the push.
    33  
    34  However, it's not always the case that the entire directory should be uploaded. Often,
    35  temporary or cache directories and files like `.git`, `.tmp` will be included by default, which
    36  can cause failures at certain sizes and should be avoided. You can
    37  specify [exclusions](https://terraform.io/docs/commands/push.html) to avoid this situation.
    38  
    39  Terraform also allows for a [VCS option](https://terraform.io/docs/commands/push.html#_vcs_true)
    40  that will detect your VCS (if there is one) and only upload the files that are tracked by the VCS. This is
    41  useful for automatically excluding ignored files. In a VCS like git, this
    42  basically does a `git ls-files`.
    43  
    44  
    45  ## GitHub Webhooks
    46  
    47  Optionally, GitHub can be used to import Terraform configuration. When used
    48  within an organization, this can be extremely valuable for keeping differences
    49  in environments and last mile changes from occurring before an upload.
    50  
    51  After you have [connected your GitHub account to Terraform Enterprise](/docs/enterprise/vcs/github.html),
    52  you can connect your environment to the target
    53  GitHub repository. The GitHub repository will be linked to the Terraform Enterprise
    54  configuration, and GitHub will start sending webhooks. Certain
    55  GitHub webhook events, detailed below, will cause the repository to be
    56  automatically ingressed into Terraform and stored, along with references to the
    57  GitHub commits and authorship information.
    58  
    59  Currently, an environment must already exist to be connected to GitHub. You can
    60  create the environment with `terraform push`, detailed above, and then link it
    61  to GitHub.
    62  
    63  Each ingress will trigger a Terraform plan. If you have auto-apply enabled then
    64  the plan will also be applied.
    65  
    66  You can disable an ingress by adding the text `[atlas skip]` or `[ci skip]` to
    67  your commit message.
    68  
    69  Supported GitHub webhook events:
    70  
    71  - pull_request (on by default)
    72    - ingress when opened or reopened
    73    - ingress when synchronized (new commits are pushed to the branch)
    74  - push (on by default)
    75    - ingress when a tag is created
    76    - ingress when the default branch is updated
    77      - note: the default branch is either configured on your configuration's
    78        integrations tab, or if that is blank it is the GitHub
    79        repository's default branch
    80  - create (off by default)
    81    - ingress when a tag is created
    82    - note: if you want to only run on tag creation, turn on create events and
    83      turn off push events
    84  
    85  ## Artifact Uploads
    86  
    87  Upon successful completion of a Terraform run, the remote state is parsed and
    88  any [artifacts](/docs/enterprise/artifacts/artifact-provider.html) are detected that
    89  were referenced. When new versions of those referenced artifacts are uploaded, you have the option to automatically queue a new Terraform run.
    90  
    91  For example, consider the following Terraform configuration which references an
    92  artifact named "worker":
    93  
    94  ```hcl
    95  resource "aws_instance" "worker" {
    96    ami           = "${atlas_artifact.worker.metadata_full.region-us-east-1}"
    97    instance_type = "m1.small"
    98  }
    99  ```
   100  
   101  When a new version of the and artifact "worker" is uploaded either manually
   102  or as the output of a [Packer build](/docs/enterprise/packer/builds/starting.html), a Terraform plan can be automatically triggered with this new artifact version.
   103  You can enable this feature on a per-environment basis from the
   104  environment settings page.
   105  
   106  Combined with
   107  [Terraform auto apply](/docs/enterprise/runs/automatic-applies.html), you can
   108  continuously deliver infrastructure using Terraform and Terraform Enterprise.
   109  
   110  ## Terraform Plugins
   111  
   112  If you are using a custom [Terraform Plugin](https://www.terraform.io/docs/plugins/index.html)
   113  binary for a provider or provisioner that's not currently in a released
   114  version of Terraform, you can still use this in Terraform Enterprise.
   115  
   116  All you need to do is include a Linux AMD64 binary for the plugin in the
   117  directory in which Terraform commands are run from; it will then be used next time you `terraform push` or ingress from GitHub.