@@ -690,7 +690,7 @@ with `review/` would have that variable available.
Some GitLab features can behave differently for each environment.
For example, you can
[create a secret variable to be injected only into a production environment](../variables/README.md#limit-the-environment-scopes-of-cicd-variables).
[create a project CI/CD variable to be injected only into a production environment](../variables/README.md#limit-the-environment-scope-of-a-cicd-variable).
In most cases, these features use the _environment specs_ mechanism, which offers
an efficient way to implement scoping in each environment group.
@@ -220,7 +220,7 @@ the ones defined in the upstream project take precedence.
#### With variable inheritance
You can pass variables to a downstream pipeline with [`dotenv` variable inheritance](variables/README.md#inherit-cicd-variables) and [cross project artifact downloads](yaml/README.md#cross-project-artifact-downloads-with-needs).
You can pass variables to a downstream pipeline with [`dotenv` variable inheritance](variables/README.md#pass-an-environment-variable-to-another-job) and [cross project artifact downloads](yaml/README.md#cross-project-artifact-downloads-with-needs).
1. Using [push options](../../user/project/push_options.md#push-options-for-gitlab-cicd).
1. Manually triggering pipelines with [the API](../triggers/README.md#making-use-of-trigger-variables).
1. Passing variables to a [downstream pipeline](../multi_project_pipelines.md#passing-cicd-variables-to-a-downstream-pipeline).
You can grant permission to override variables to [maintainers](../../user/permissions.md#project-features) only. When other users try to run a pipeline
with overridden variables, they receive the `Insufficient permissions to set pipeline variables`
error message.
These pipeline variables declared in these events take [priority over other variables](#priority-of-cicd-variables).
If you [store your CI/CD configurations in a different repository](../../ci/pipelines/settings.md#custom-cicd-configuration-path),
use this setting for control over the environment the pipeline runs in.
#### Restrict who can override variables
You can enable this feature by using [the projects API](../../api/projects.md#edit-project)
to enable the `restrict_user_defined_variables` setting. The setting is `disabled` by default.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/295234) in GitLab 13.8.
## Limit the environment scope of a CI/CD variable
To allow only users with Maintainer role to set these variables, you can use
[the API](../../api/projects.md#edit-project) to enable the project setting `restrict_user_defined_variables`.
When a user without Maintainer role tries to run a pipeline with overridden
variables, an `Insufficient permissions to set pipeline variables` error occurs.
You can limit the environment scope of a variable by
[defining which environments](../environments/index.md) it can be available for.
The setting is `disabled` by default.
To learn more about scoping environments, see [Scoping environments with specs](../environments/index.md#scoping-environments-with-specs).
If you [store your CI/CD configurations in a different repository](../../ci/pipelines/settings.md#custom-cicd-configuration-path),
use this setting for strict control over all aspects of the environment
the pipeline runs in.
## Deployment variables
#### Override a variable by manually running a pipeline
Integrations that are responsible for deployment configuration can define their own
variables that are set in the build environment. These variables are only defined
for [deployment jobs](../environments/index.md).
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44059) in GitLab 10.8.
For example, the [Kubernetes integration](../../user/project/clusters/index.md#deployment-variables)
defines deployment variables that you can use with the integration.
You can override the value of a current variable by
[running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually).
The [documentation for each integration](../../user/project/integrations/overview.md)
explains if the integration has any deployment variables available.
For instance, suppose you added a custom variable named `$TEST`
and you want to override it in a manual pipeline.
## Auto DevOps environment variables
Go to your project's **CI/CD > Pipelines** and select **Run pipeline**.
Choose the branch you want to run the pipeline for, then add a variable and its value in the UI:
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/49056) in GitLab 11.7.
CI/CD variables with multi-line values are not supported.
## CI/CD variable expressions
...
...
@@ -828,44 +822,22 @@ testvariable:
> Introduced in GitLab Runner 1.7.
WARNING:
Enabling debug tracing can have severe security implications. The
output **will** contain the content of all your variables and any other
secrets! The output **will** be uploaded to the GitLab server and made visible
in job logs!
By default, the runner hides most of the details of what it is doing when
processing a job. This behavior keeps job logs short, and prevents secrets
from being leaked into the log unless your script writes them to the screen.
If a job isn't working as expected, this can make the problem difficult to
investigate; in these cases, you can enable debug tracing in `.gitlab-ci.yml`.
Available on GitLab Runner v1.7+, this feature enables the shell's execution log. This results in a verbose job log listing all commands that were run, variables that were set, and so on.
Before enabling this, you should ensure jobs are visible to
[team members only](../../user/permissions.md#project-features). You should
also [erase](../jobs/index.md#view-jobs-in-a-pipeline) all generated job logs
before making them visible again.
### Restricted access to debug logging
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213159) in GitLab 13.7.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292661) in GitLab 13.8.
Debug logging can be a serious security risk. The output contains the content of
all variables and other secrets available to the job. The output is uploaded to the
GitLab server and visible in job logs.
With restricted access to debug logging, only users with
[developer or higher permissions](../../user/permissions.md#project-members-permissions)
can view job logs when debug logging is enabled with a variable in:
You can use debug logging to help troubleshoot problems with pipeline configuration
or job scripts. Debug logging exposes job execution details that are usually hidden
by the runner and makes job logs more verbose. It also exposes all variables and secrets
available to the job.
- The [`.gitlab-ci.yml` file](#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file).
- The CI/CD variables set in the GitLab UI.
WARNING:
If you add `CI_DEBUG_TRACE` as a local variable to your runners, debug logs are visible
to all users with access to job logs. The permission levels are not checked by Runner,
so you should make use of the variable in GitLab only.
Before you enable debug logging, make sure only [team members](../../user/permissions.md#project-features)
can view job logs. You should also [delete job logs](../jobs/index.md#view-jobs-in-a-pipeline)
with debug output before you make logs public again.
### Enable Debug logging
To enable debug logs (traces), set the `CI_DEBUG_TRACE` variable to `true`:
To enable debug logging (tracing), set the `CI_DEBUG_TRACE` variable to `true`:
```yaml
job_name:
...
...
@@ -873,11 +845,10 @@ job_name:
CI_DEBUG_TRACE:"true"
```
Example truncated output with `CI_DEBUG_TRACE` set to `true`:
You can specify the use of a custom Helm chart per environment by scoping the CI/CD variable
to the desired environment. See [Limiting environment scopes of variables](../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables).
to the desired environment. See [Limit environment scope of CI/CD variables](../../ci/variables/README.md#limit-the-environment-scope-of-a-cicd-variable).
