Skip to content

Commit 5f628b6

Browse files
kcbimontekcbimonte
committed
docx: git guides complete
Signed-off-by: Kevin Bimonte <kbimonte@gmail.com>
1 parent 4359747 commit 5f628b6

File tree

2 files changed

+221
-1
lines changed

2 files changed

+221
-1
lines changed

‎docs/docs/how-to/git-guides/basic.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,111 @@ Check out the [docs](https://github.com/concourse/git-resource) for the git reso
1414

1515
## Fetching a Repository
1616

17+
Here is how you fetch the contents of a git repository and use it in a task.
18+
19+
```yaml
20+
resources:
21+
- name: concourse-examples
22+
type: git
23+
icon: github
24+
source:
25+
uri: https://github.com/concourse/examples
26+
27+
jobs:
28+
- name: read-the-readme
29+
plan:
30+
- get: concourse-examples
31+
- task: cat-readme
32+
config:
33+
platform: linux
34+
image_resource:
35+
type: registry-image
36+
source:
37+
repository: busybox
38+
inputs: # pass concourse-examples into this task step
39+
- name: concourse-examples
40+
run:
41+
path: cat
42+
args: [ "concourse-examples/README.md" ]
43+
```
44+
1745
## Creating Commits and Tags
1846
47+
Here's a simple way to create a commit using a bash script.
48+
49+
```yaml
50+
resources:
51+
- name: repo-main
52+
type: git
53+
icon: github
54+
source:
55+
uri: https://github.com/user/my-repo
56+
branch: main
57+
58+
jobs:
59+
- name: create-a-commit
60+
plan:
61+
- get: repo-main
62+
- task: commit-and-tag
63+
config:
64+
platform: linux
65+
image_resource:
66+
type: registry-image
67+
source:
68+
repository: gitea/gitea # use any image that has the git cli
69+
inputs:
70+
- name: repo-main
71+
outputs:
72+
# to pass the commit to the following steps specify
73+
# the "repo-main" as an output as well
74+
- name: repo-main
75+
run:
76+
path: sh
77+
args:
78+
- -cx
79+
# this is just a bash script
80+
- |
81+
cd repo-main
82+
# edit a file / make a change
83+
date +%Y-%m-%d > todays-date
84+
git add ./todays-date
85+
git commit -m "Add todays date"
86+
git tag v0.1.6
87+
# push commit and tag
88+
- put: repo-main
89+
params:
90+
# specify the "repo-main" artifact as the location
91+
repository: repo-main
92+
```
93+
1994
## Merging Branches
95+
96+
Here is how you can merge two branches. Common if you are
97+
using [gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) and need to merge a `dev`
98+
branch into `main` every so often.
99+
100+
```yaml
101+
resources:
102+
- name: repo-main
103+
type: git
104+
icon: github
105+
source:
106+
uri: https://github.com/user/my-repo
107+
branch: main
108+
109+
- name: repo-dev
110+
type: git
111+
icon: github
112+
source:
113+
uri: https://github.com/user/my-repo
114+
branch: dev
115+
116+
jobs:
117+
- name: merge-dev-into-main
118+
plan:
119+
- get: repo-dev
120+
- put: repo-main
121+
params:
122+
repository: repo-dev
123+
merge: true
124+
```

‎docs/docs/how-to/git-guides/multi-branch.md‎

Lines changed: 116 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,123 @@
22
title: Multi-Branch Workflows
33
---
44

5+
Teams may make use of multiple branches for their development. For instance, some teams create feature branches while
6+
working on new functionality - once this functionality is ready, the branch will be merged into the main branch and the
7+
feature branch will be deleted.
8+
9+
While a feature is under development, you'll often want to run tests against the feature branch and possibly deploy to a
10+
staging environment. To model this in Concourse, you'll need to have a pipeline for each active feature branch. Manually
11+
setting (and eventually archiving) a pipeline for each feature branch would be quite a burden. For this type of
12+
workflow, Concourse has a few important tools to help you out: the [`set_pipeline` step](../../steps/set-pipeline.md), [
13+
`across`](../../steps/modifier-and-hooks/across.md), and [instanced pipelines](../../pipelines/grouping-pipelines.md).
14+
15+
!!! warning "Experimental Feature"
16+
17+
[`across`](../../steps/modifier-and-hooks/across.md) and [instanced
18+
pipelines](../../pipelines/grouping-pipelines.md) are both experimental features, and must be enabled with the
19+
feature flags `CONCOURSE_ENABLE_ACROSS_STEP` and `CONCOURSE_ENABLE_PIPELINE_INSTANCES`, respectively.
20+
21+
In this guide, we'll cover:
22+
23+
1. Writing a pipeline to [Test, Build & Deploy](#test-build-deploy) a branch to a staging environment. We'll
24+
use [Terraform](https://www.terraform.io/) for our deployment
25+
2. [Tracking Branches](#tracking-branches) in a repository; for each branch, we'll set a pipeline (using the [
26+
`set_pipeline` step](../../steps/set-pipeline.md) and [across](../../steps/modifier-and-hooks/across.md))
27+
3. Automatically [Cleaning Up Old Workspaces](#cleaning-up-old-workspaces) after branches get merged or deleted
28+
529
## Test, Build & Deploy
630

31+
We'll start out by defining the pipeline that should run for each active branch. For this example, we'll be working with
32+
the following [sample Go application](https://github.com/concourse/examples/tree/master/apps/golang).
33+
34+
Our pipeline will have three stages:
35+
36+
1. Run unit tests
37+
2. Build and upload a binary to a blobstore (in our case, we'll
38+
use [Google Cloud Storage](https://cloud.google.com/storage))
39+
3. Trigger a `terraform apply` to deploy our app to a staging environment.
40+
The [Terraform module](https://github.com/concourse/examples/blob/master/terraform/staging/main.tf) we'll use here
41+
doesn't actually provision any infrastructure, and is just used as an example
42+
43+
Since the pipeline config is intended to be used as a template for multiple different branches, we can
44+
use [Vars](../../vars.md) to parameterize the config. In particular, we'll use the vars `((feature))` and `((branch))`,
45+
which represent the name of the feature and the name of the branch, respectively.
46+
47+
Below is the full pipeline config from
48+
the [Examples Repo](https://github.com/concourse/examples/blob/master/pipelines/multi-branch/template.yml):
49+
50+
```yaml linenums="1" title="template.yml"
51+
--8<-- "libs/examples/pipelines/multi-branch/template.yml"
52+
```
53+
754
## Tracking Branches
855

9-
## Cleaning Up Old Workspaces
56+
In addition to the branch pipeline template, we'll also need a pipeline to track the list of branches and set a pipeline
57+
for each one.
58+
59+
To track the list of branches in a repository, we can use [
60+
`aoldershaw/git-branches-resource`](https://github.com/aoldershaw/git-branches-resource). This [
61+
`resource_type`](../../resource-types/index.md) emits a new [resource version](../../resources/resource-versions.md)
62+
whenever a branch is created or deleted. It also lets us filter the list of branches by a regular expression. In this
63+
case, let's assume our feature branches match the regular expression `feature/.*`.
64+
65+
Below is the current pipeline config for this tracker pipeline:
66+
67+
```yaml linenums="1" title="tracker.yml"
68+
resource_types:
69+
- name: git-branches
70+
type: registry-image
71+
source:
72+
repository: aoldershaw/git-branches-resource
73+
74+
resources:
75+
- name: feature-branches
76+
type: git-branches
77+
source:
78+
uri: https://github.com/concourse/examples
79+
# The "(?P<name>pattern)" syntax defines a named capture group.
80+
# aoldershaw/git-branches-resource emits the value of each named capture
81+
# group under the `groups` key.
82+
#
83+
# e.g. feature/some-feature ==> {"groups": {"feature": "some-feature"}}
84+
branch_regex: 'feature/(?P<feature>.*)'
85+
86+
- name: examples
87+
type: git
88+
source:
89+
uri: https://github.com/concourse/examples
90+
91+
jobs:
92+
- name: set-feature-pipelines
93+
plan:
94+
- in_parallel:
95+
- get: feature-branches
96+
trigger: true
97+
- get: examples
98+
- load_var: branches
99+
file: feature-branches/branches.json
100+
- across:
101+
- var: branch
102+
values: ((.:branches))
103+
set_pipeline: dev
104+
file: examples/pipelines/multi-branch/template.yml
105+
instance_vars: { feature: ((.:branch.groups.feature)) }
106+
vars: { branch: ((.:branch.name)) }
107+
```
108+
109+
We set each pipeline as an [instanced pipeline](../../pipelines/grouping-pipelines.md) - this will result in Concourse
110+
grouping all the related `dev` pipelines in the UI.
111+
112+
## Cleaning Up Old Workspaces
113+
114+
With the setup described in [Tracking Branches](#tracking-branches), Concourse will automatically archive any pipelines
115+
for branches that get removed. However, Concourse doesn't know that it should destroy Terraform workspaces when a branch
116+
is removed. To accomplish this, we can yet again make use of
117+
the [Terraform resource](https://github.com/ljfranklin/terraform-resource) to destroy these workspaces. We'll add
118+
another job to
119+
the [tracker pipeline](https://github.com/concourse/examples/blob/master/pipelines/multi-branch/tracker.yml) that
120+
figures out which workspaces don't belong to an active branch and destroy them.
121+
122+
```yaml linenums="1" title="template.yml"
123+
--8<-- "libs/examples/pipelines/multi-branch/tracker.yml"
124+
```

0 commit comments

Comments
 (0)