### **The event**
Unlike GitHub workflows, GitLab pipelines are triggered[^1] when *any* commit is pushed to your repository. In our case,
we only want the pipeline to run when a tag is pushed or created. Instead of defining the specific event we want to
trigger our pipeline, we'll build a set of rules to define which type of push should trigger our pipeline. To build
these rules we'll utilize the `workflow` [property](https://docs.gitlab.com/ee/ci/yaml/workflow.html) which controls
when pipelines are run.
```yaml {filename=".gitlab-ci.yml"} theme={null}
workflow:
name: Deploy to Platform.sh on tag
rules:
- if: $CI_COMMIT_TAG && $CI_PIPELINE_SOURCE == "push"
```
The predefined CI/CD variable `$CI_COMMIT_TAG` contains the commit tag name and, most importantly, is only set in tag
pipelines. The `$CI_PIPELINE_SOURCE` variable contains how the pipeline was triggered. Since we want a tag push, we want
to only run this pipeline if the trigger is a `push` event. I've also added a `name` property so this pipeline is easier
to identify in the repository's pipelines area.
### **The stages**
Like with GitHub, we'll need to define a series of jobs that perform the tasks. And also just like with GitHub, jobs run
in parallel by default. However, unlike GitHub Actions, GitLab gives us a way to control the order in which jobs run
with [stages](https://docs.gitlab.com/ee/ci/yaml/#stages). The stages are executed in order[^2], and later stages can
only start at earlier stages that have been completed.
Before we define our jobs, we'll define the stages that should occur, and then we'll attach jobs[^3] to their relevant
stage.
```yaml {filename=".gitlab-ci.yml"} theme={null}
stages:
- setup
- perform
```
I've defined a `setup` stage, where I'll add the jobs that check to see if the tag that was pushed is one we want to
deploy to Platform.sh, and a `perform` stage where I'll add the jobs to perform the push.
### **Caching**
You might be wondering, "Why is there a section on caching when we just want to see if we need to push, and why is it
before we've defined any jobs?" Unlike GitHub and its
[outputs](https://docs.github.com/en/actions/using-jobs/defining-outputs-for-jobs), GitLab does not provide a
straightforward way to share small bits of data between jobs and stages. To facilitate data sharing they instead
utilize [artifacts](https://docs.gitlab.com/ee/ci/caching/#artifacts) and
[cache](https://docs.gitlab.com/ee/ci/caching/#cache).
In either case, we have to use a file to store the data we want to share. Since
[job artifacts](https://docs.gitlab.com/ee/ci/jobs/job_artifacts.html) were specifically designed for sharing
intermediate build results between stages, in the case of just needing to pass a small bit of data to the next stage,
it's overkill. Instead, for this pipeline, we'll set up caching and cache a single file to share data between our stages.
Caching needs to be set up on a per-job basis but since we want both stages and their jobs to access the same cache,
we'll define our cache instead in the [default](https://docs.gitlab.com/ee/ci/yaml/#default) area of our pipeline.
```yaml {filename=".gitlab-ci.yml"} theme={null}
default:
cache: &global_cache
key: push-to-psh
paths:
- "push.txt"
when: always
```
Here I'm using a [yaml anchor](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases) ( `&global_cache`) to set up a
reusable cache definition at the global level that I then reference in each job, but with the ability to override any
properties as needed. A cache is required to have a [unique](https://docs.gitlab.com/ee/ci/yaml/index.html#cachekey)
`key`, and jobs that use the same cache key will use the same cache. Perfect for what we need!
We then define the file we want to cache (`push.txt`) using the `paths`
[property](https://docs.gitlab.com/ee/ci/yaml/index.html#cachepaths) and instruct GitLab to `always` save the cache with
`when`.
### **The jobs**
Now I'll define my jobs and attach them to the stage where they should run. To make things easy to read, I'll define the
job in the `setup` stage first and attach it to `setup` using the `stage` property:
```yaml {filename=".gitlab-ci.yml"} theme={null}
should_we_push:
stage: setup
```
By default, GitLab checks out a
[shallow clone](https://docs.gitlab.com/ee/ci/pipelines/settings.html#limit-the-number-of-changes-fetched-during-clone)
of your repository based on the commit that was pushed. In our case, we want to see if the tag that was pushed is the
closest tag to the latest commit on our default branch so we'll instruct GitLab instead to checkout the default branch.
We can do so by using the `before_script` property. Any steps defined in `before_script` are executed before the job is
started which allows us to alter the default behavior:
```yaml {filename=".gitlab-ci.yml"} theme={null}
should_we_push:
stage: setup
before_script:
- git fetch origin "${CI_DEFAULT_BRANCH}"
- git fetch --tags
- git checkout "${CI_DEFAULT_BRANCH}"
```
Now before the `should_we_push` job begins, we'll fetch any changes from GitLab, then fetch all the tags, and finally
checkout the default branch. This is fairly similar to what we accomplished in the GitHub Actions article when we used
the actions/checkout action to checkout our repository using the default branch with a depth of 0. The `script` section
seen below contains the commands we want our runner to execute.
Or to locate your project’s ID from the command line, when in the local copy of your project, you can run the following
command:
```bash {filename="Terminal"} theme={null}
❯ platform project:info id
ropxcgtns2wgy
```
From there, follow the
[GitLab directions](https://docs.gitlab.com/ee/ci/variables/index.html#define-a-cicd-variable-in-the-ui) for adding a
CI/CD variable in the UI, adding one for `PLATFORM_CLI_TOKEN`[^5] and one for `PROJID`, setting the values as appropriate.
