Skip to main content

Authentication & Secrets

A hook often needs to call a cloud API or reach an external service: to inspect live resources, fetch a secret, or post a notification. The authentication block on an after_hook gives the hook's execute command a cloud identity to do this. When it is present, Pipelines authenticates and makes the resulting credentials available to the hook before running its command. When it is omitted, the hook runs with no cloud credentials.

Cloud credentials​

The authentication block authenticates the hook against a cloud provider. It supports AWS, Azure, and GCP through their OIDC blocks (aws_oidc, azure_oidc, gcp_oidc), as well as a custom block that runs your own command to obtain credentials. Each provider takes a separate identity for plan and for apply: Pipelines authenticates with the plan identity when the hook runs after a plan, and the apply identity when it runs after an apply. The two can be the same or different.

Once the hook is authenticated, the provider's CLIs and SDKs work inside it with no further configuration. Configure the block for your provider:

repository {
  after_hook "inspect_resources" {
    commands = ["plan"]
    execute  = [".gruntwork/hooks/inspect-resources.sh"]

    authentication {
      aws_oidc {
        account_id         = "123456789012"
        plan_iam_role_arn  = "arn:aws:iam::123456789012:role/pipelines-plan"
        apply_iam_role_arn = "arn:aws:iam::123456789012:role/pipelines-apply"
      }
    }
  }
}

For setting up each provider and the full set of fields, see Authenticating to the Cloud and the authentication block reference.

Secrets​

Pipelines does not load secrets into a hook for you. It is up to the hook author to decide how a secret is stored and retrieved. What the authentication block provides is the context, a cloud identity, that lets the hook retrieve the secret itself at runtime.

The pattern is the same whatever your provider: store the secret in a secret store, grant the hook's identity permission to read it, and have the hook fetch it at runtime using the credentials the authentication block already provides. The secret never appears in your configuration or the hook script.

For a working example using AWS and SSM Parameter Store, see Slack Deploy Notification. For other ways to manage and supply secrets across Pipelines, see Managing Secrets in your Pipelines.